格局判定

本命与运限的格局命中、PatternConfig 口径、PatternKey 枚举与判断方法。

格局是「盘上某几颗星按特定方式凑在一起」的模式识别。判定在本命盘与运限盘上共用同一套规则，共 64 条。什么是格局、每条规则的条件与来源，见概念页。

from x_iztro import Astro

chart = Astro().by_solar("1985-5-3", 9, "male")
hits = chart.patterns()

本页示例统一用默认的 zh-CN 本命盘，因此输出里的展示值都是中文。

类型

PatternHit、PatternStar、PatternConfig 是 frozen dataclass， PatternKey、BrightnessSource 是 StrEnum，全部从 x_iztro 顶层导出。

PatternHit

字段	类型	说明
`key`	`str`	语言无关格局标识，取值域即 `PatternKey`
`name`	`str`	格局名称，按排盘语言翻译
`scope`	`str`	判定视角：本命为 `"origin"`，运限为该层
`palace_index`	`int`	成格所在的宫位索引（0-11，寅宫为 0）
`palace_name`	`str`	该宫在这个视角下的宫名
`palace_name_key`	`str`	宫名标识，取值域即 `PalaceName`
`variant`	`str \| None`	多口径格局命中的口径；单口径为 `None`
`broken`	`bool`	「破格 / 加杀平常」条件是否触发。成格照报，这里只作标记
`stars`	`list[PatternStar]`	参与成格的星与落宫

三个方法：

方法	说明
`is_(key)`	是否为指定格局，收 `PatternKey` 或字符串
`in_palace(name)`	成格宫位在该视角下是否为指定宫名，收 `PalaceName`、宫名标识或当前语言宫名
`to_dict()`	绑定层返回的原始 DTO（camelCase 键）

PatternStar

字段	类型	说明
`key`	`str`	语言无关星耀标识
`name`	`str`	星耀名称，按排盘语言翻译
`palace_index`	`int`	该星真正待的宫位索引（借宫时不是借到的那一宫）
`brightness` / `brightness_key`	`str \| None`	亮度显示文本与标识；无亮度为 `None`
`mutagen` / `mutagen_key`	`str \| None`	判定视角下的四化与标识；无四化为 `None`

两个方法：has_brightness(b)、has_mutagen(m)，都比标识，与排盘语言无关。

PatternConfig

判定口径。凡是「同一格局的多种成立形式」都走 PatternHit.variant，这里只放会改变 事实判定本身的数据口径，因此只有三个字段。

from x_iztro import PatternConfig, BrightnessSource

PatternConfig(
    brightness_source=BrightnessSource.TABLE,  # 默认
    borrow=True,                               # 默认
    flow_stars=True,                           # 默认
)

字段	默认	作用
`brightness_source`	`BrightnessSource.TABLE`	日月明暗的依据
`borrow`	`True`	空宫是否借对宫主星参与判定
`flow_stars`	`True`	运限视角下流曜（运禄/流禄、运昌/流昌…）是否等同对应本命辅星

BrightnessSource 两个成员：TABLE 按星盘亮度表（庙旺为明，陷与「不」为暗，与 iztro 逐值一致）， POSITIONAL 按传统位置（太阳寅至午明、酉至丑暗；太阴酉至丑明、卯至未暗）。两者的取舍见概念页的说明。

PatternConfig 是 frozen dataclass，改一项用 dataclasses.replace，或直接构造一个新的——三个字段都有默认值，只写要改的那个即可。

PatternKey

64 个格局的语言无关标识，StrEnum，可直接与 PatternHit.key 比较：

from x_iztro import PatternKey

print(len(list(PatternKey)))
print(PatternKey.SHA_PO_LANG)
print(PatternKey("sha_po_lang").name)

64
sha_po_lang
SHA_PO_LANG

patterns

用途　取本命盘的全部格局命中。

斗数含义　把这张盘上成立的所有有名字的星耀组合列出来，附上成格的宫位与证据星。

签名

def patterns(self, config: PatternConfig | None = None) -> list[PatternHit]

参数

参数	类型	必填	默认	说明
`config`	`PatternConfig \| None`	否	`None`	判定口径；不传即默认口径

返回值　list[PatternHit]——按来源页条目顺序排列；一条格局也不成立时为空列表。本命盘上两条行运格（禄衰马困、风云际会）永远不出现。

示例

chart = Astro().by_solar("1985-5-3", 9, "male")

for hit in chart.patterns():
    print(f"{hit.name} {hit.palace_index} {hit.palace_name} broken={hit.broken}")

输出

武贪同行 11 迁移 broken=False
府相朝垣 5 命宫 broken=False
杀破狼 11 迁移 broken=False
禄马交驰 5 命宫 broken=False
左右夹命 5 命宫 broken=False
文贵文华 11 迁移 broken=False
文星朝命 5 命宫 broken=True
文星暗拱 5 命宫 broken=False
文星暗拱 5 命宫 broken=False

取一条命中并读它的证据星：

from x_iztro import PatternKey, PalaceName

hit = next(h for h in chart.patterns() if h.is_(PatternKey.FU_XIANG_CHAO_YUAN))

print(hit.name, hit.variant, hit.in_palace(PalaceName.SOUL))
for s in hit.stars:
    print(" ", s.name, s.palace_index, s.brightness, s.brightness_key)

府相朝垣 soul_empty True
  天府 9 得 de
  天相 1 陷 xian

按口径判：

from x_iztro import PatternConfig, BrightnessSource

chart = Astro().by_solar("1985-1-5", 11, "female")

print([h.name for h in chart.patterns()])
print([h.name for h in chart.patterns(
    PatternConfig(brightness_source=BrightnessSource.POSITIONAL))])

['禄马交驰', '左右夹命', '坐贵向贵']
['日月并明', '禄马交驰', '左右夹命', '坐贵向贵']

边界与陷阱

Horoscope.patterns

用途　取某个运限层级视角下的格局命中。

斗数含义　以该层的命宫为命宫、合并该层的流曜与四化之后重跑全部规则。「本命有此组合，大限又走到即享其益」就是这么算出来的。

签名

def patterns(
    self,
    scope: Scope | ScopeLiteral,
    config: PatternConfig | None = None,
    astrolabe: Astrolabe | None = None,
) -> list[PatternHit]

参数

参数	类型	必填	默认	说明
`scope`	`Scope \| str`	是	—	判定视角所在的层级
`config`	`PatternConfig \| None`	否	`None`	判定口径
`astrolabe`	`Astrolabe \| None`	否	`None`	星盘；省略时取发起本次运限查询的那张盘

返回值　list[PatternHit]，每条的 scope 即传入的层级。传 Scope.ORIGIN 时结果与本命盘上直接调 patterns() 完全一致。

异常　ValueError——既没传 astrolabe、本运限也不是由星盘发起时抛出。用 chart.horoscope(...) 拿到的运限对象不会遇到这种情况。

示例

from x_iztro import Scope

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

for hit in h.patterns(Scope.DECADAL):
    print(hit.name, hit.scope, hit.variant)

print(h.patterns("origin") == chart.patterns())

输出

杀破狼 decadal None
风云际会 decadal None
风云际会 decadal yearly
True

同一张盘的本命视角只有一条「府相朝垣」——大限换了命宫，杀破狼才在这一层成立。

边界与陷阱

to_dict

用途　取绑定层返回的原始 DTO：camelCase 键，值按排盘语言翻译，同时带语言无关标识。需要把命中原样落库、发给前端或喂给模型时用它。

签名

def to_dict(self) -> dict[str, Any]

示例

import json

chart = Astro().by_solar("1985-5-3", 9, "male")
hit = next(h for h in chart.patterns() if h.is_(PatternKey.FU_XIANG_CHAO_YUAN))
print(json.dumps(hit.to_dict(), ensure_ascii=False, indent=2))

输出

{
  "broken": false,
  "key": "fu_xiang_chao_yuan",
  "name": "府相朝垣",
  "palaceIndex": 5,
  "palaceName": "命宫",
  "palaceNameKey": "soulPalace",
  "scope": "origin",
  "stars": [
    {
      "brightness": "得",
      "brightnessKey": "de",
      "key": "tianfuMaj",
      "name": "天府",
      "palaceIndex": 9
    },
    {
      "brightness": "陷",
      "brightnessKey": "xian",
      "key": "tianxiangMaj",
      "name": "天相",
      "palaceIndex": 1
    }
  ],
  "variant": "soul_empty"
}

无值的可选键（variant、亮度、四化）在 DTO 里直接省略，不会出现 null。

patterns_to_text

用途　格局命中的语义化文本，每条一行：格局名、命中宫、构成星耀，破格标 [破格]。

签名

def patterns_to_text(self, config: PatternConfig | None = None) -> str          # Astrolabe
def patterns_to_text(self, scope, config=None, astrolabe=None) -> str           # Horoscope

与 patterns 同一套判定（含重排上下文与判定口径）；运限版本的宫名按该层重排后的宫名书写。

示例

print(chart.patterns_to_text(), end="")

输出

- 府相朝垣(命宫): 天府(庙), 天相(庙)

运限视角同形：chart.horoscope("2025-1-1", 0).patterns_to_text("yearly")，宫名按流年重排后的宫名书写。

本命盘与运限的 to_text 已各自带格局节；单独调用适合只要格局摘要的场景。

格局判定

palace_index 未必是命宫

stars 里的 palace_index 是星真正待的宫

判断逻辑用标识，不要比译名

运限视角没有身宫

两条行运格只在运限出现

流曜等同本命辅星

接口无状态

本页目录