x-iztro

紫微斗数 Rust 核心库，移植自 iztro v2.5.8。

提供排盘、运限、三方四正、四化飞星等完整功能，支持 Rust / Python / Go 三种语言调用。

安装

Rust

# Cargo.toml
[dependencies]
x-iztro = { git = "https://github.com/x-haose/x-iztro" }

Python

pip install maturin
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 maturin develop --features python

Go

Go 包内嵌 wasm、经纯 Go 的 wazero 运行时调用，无 cgo、无需本机 Rust 工具链：

go get github.com/x-haose/x-iztro/go/iztro

开发者更新内嵌 wasm：

cargo build --release --target wasm32-wasip1
cp target/wasm32-wasip1/release/x_iztro.wasm go/iztro/

快速开始

Rust

use x_iztro::{IztroError, by_solar, get_horoscope};
use x_iztro::data::types::*;

// Config 控制分界点与派别：year_divide / horoscope_divide / age_divide /
// day_divide / algorithm，默认值与 JS iztro 一致；
// 入参非法（日期格式/范围、时辰索引）时返回 Err(IztroError)
let astrolabe = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
println!("命主：{:?}", astrolabe.soul);

// 中州派：Config { algorithm: Algorithm::Zhongzhou, ..Config::default() }

let horoscope = get_horoscope(&astrolabe, "2024-1-1", 0, Language::ZhCN)?;
println!("流年四化：{:?}", horoscope.yearly.base.mutagen);

Python

from x_iztro import Astro, ChartConfig
from x_iztro.enums import Algorithm, MajorStar, Mutagen, PalaceName

astro = Astro()
result = astro.by_solar("2000-8-16", 2, "female")
# 配置：astro.by_solar(..., config=ChartConfig(algorithm=Algorithm.ZHONGZHOU))

# 枚举基于语言无关 key，在任何输出语言的星盘上判断结果一致
soul = result.palace(PalaceName.SOUL)
print(f"命主：{result.soul}")
print(f"命宫有紫微：{soul.has([MajorStar.ZIWEI])}")
print(f"命宫化禄：{soul.has_mutagen(Mutagen.LU)}")

horoscope = astro.get_horoscope(result, "2024-1-1", 0)
print(f"流年：{horoscope.yearly.heavenly_stem}{horoscope.yearly.earthly_branch}")
print(f"岁前十二神：{horoscope.yearly.yearly_dec_star.suiqian12}")

Go

import "github.com/x-haose/x-iztro/go/iztro"

// 返回类型化结构体；key 常量在任何输出语言下都有效
result, _ := iztro.BySolar("2000-8-16", 2, "female", true, "zh_cn", nil)
fmt.Println(result.Soul)

soul := result.Palace(iztro.PalaceSoul)
fmt.Println(soul.Has(iztro.StarZiweiMaj), soul.HasMutagen(iztro.MutagenLu))

// 中州派：iztro.BySolar(..., &iztro.Config{Algorithm: "zhongzhou"})
h, _ := iztro.GetHoroscope("2000-8-16", 2, "female", true, "zh_cn", nil, "2024-1-1", 0)
fmt.Println(h.Yearly.HeavenlyStem, h.Yearly.Mutagen)

错误处理

全部外部输入在核心层前置校验：日期格式与存在性、公历 1583-9999 年（下限为格里历改革次年、上限为农历表终点）、时辰索引 0-12。非法输入的表现按语言：

Rust — 排盘入口返回 Result<_, IztroError>
Python — 抛 ValueError（消息含具体原因）
Go — 返回 error
C FFI — 返回 {"error":"..."} JSON（serde 生成，转义完备）

示例项目

examples/ 下有三个独立可运行的完整项目：

examples/rust/     # cargo run
examples/python/   # python main.py
examples/go/       # go run .

测试

运行测试

# 常规测试（单元 + tier1/tier2/运限/变体/配置/契约金标，~15 秒）
cargo test

# Tier 3 全参数空间（586,430 例，~20 秒）
cargo test --release --test golden_tier3 -- --ignored

# Python / Go 端到端金标
cd python && pytest tests/          # 先 maturin develop
cd go/iztro && go test ./...

金标覆盖矩阵

全部数据对照 JS iztro v2.5.8（版本锁定）生成，零容忍差异：

层级	用例数	覆盖范围	数据格式
Tier 1	780	60 年 × 13 时辰，全字段逐一比对（含展示字段与来因宫）	完整 JSON
Tier 2	37,440	60 年 × 每月 1/15 号 × 13 时辰 × 男女，紧凑比对	压缩 JSON
Tier 3	586,430	60 年每一天 × 13 时辰 × 男女 × fix_leap（闰月双份），全字段哈希	SHA-256 CSV
Horoscope	5,760	360 命盘 × 16 目标日期（12 流年支/童限/高龄/闰月/晚子时），六层级运限全字段	紧凑 JSON
Variants	14,268	by_lunar 闰月逐日（含 is_leap/fix_leap 组合）、中州派、六语言	CSV/JSON
Config	8,544	yearDivide=exact（立春窗口逐日）、dayDivide=current、ageDivide=birthday、horoscopeDivide=exact	CSV/JSON

合计约 66 万对照用例，覆盖排盘与运限的全部参数空间；另有 Python 108 例、Go 金标端到端测试（含 500 次非法输入轰炸）、C FFI 边界安全 16 例与绑定契约 JSON 逐键对照。

生成测试基准数据

cd tests/golden
npm install
node generate_tier1.mjs      # → tier1_data.json (~6MB)
node generate_tier2.mjs      # → tier2/year_*.json (60 files, ~23MB)
node generate_tier3.mjs      # → tier3/year_*.csv (60 files, ~30MB, 约 30 分钟)
node generate_horoscope.mjs  # → horoscope_data.json (~9MB)
node generate_variants.mjs   # → variants_*.csv / variants_languages.json
node generate_config.mjs     # → config_*.csv / config_*.json

哈希不一致时用生成器的 --inspect 系列参数重放 JS 单例，与 Rust 失败输出中的规范化串 diff 定位字段（格式定义见 tests/golden/canonical.mjs 与 tests/common/mod.rs）。

项目结构

src/
  lib.rs              # 公共 API
  error.rs            # IztroError 错误类型
  data/               # 枚举、常量、天干地支、星耀数据
  models/             # Astrolabe、Palace、Star、Horoscope 结构体
  astro/              # 排盘、运限、三方四正算法
  i18n/               # 多语言翻译（zh-CN/zh-TW/en-US/ja-JP/ko-KR/vi-VN）
  dto.rs              # JS 兼容序列化 DTO（三语言绑定共用）
  ffi.rs              # C FFI 导出
  wasm.rs             # wasm32 导出（Go 经 wazero 调用）
  python.rs           # PyO3 原生模块
  prompt.rs           # AI Prompt 生成

python/x_iztro/      # Python 包（dataclass 类型 + 枚举常量）
go/iztro/             # Go FFI 绑定包
examples/             # Rust / Python / Go 示例项目
tests/golden/         # JS 生成的测试基准数据

移植说明

移植自 iztro v2.5.8，核心排盘逻辑 1:1 对照
支持默认算法和中州派算法
排盘结果与 JS iztro 完全一致：金标测试覆盖全部时辰（含晚子时）与全部星耀，零容忍差异

License

MIT

Development Status
- 4 - Beta
Intended Audience
- Developers
Natural Language
- Chinese (Simplified)
Operating System
- OS Independent
Programming Language
- Python :: 3
- Rust
Topic
- Software Development :: Libraries

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

x_iztro-0.1.1.tar.gz (94.6 kB view details)

Uploaded Aug 12, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

x_iztro-0.1.1-cp310-abi3-win_amd64.whl (417.6 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+Windows x86-64

x_iztro-0.1.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (606.4 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+manylinux: glibc 2.17+ x86-64

x_iztro-0.1.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (580.4 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+manylinux: glibc 2.17+ ARM64

x_iztro-0.1.1-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (1.0 MB view details)

Uploaded Aug 12, 2026 CPython 3.10+macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

File details

Details for the file x_iztro-0.1.1.tar.gz.

File metadata

Download URL: x_iztro-0.1.1.tar.gz
Upload date: Aug 12, 2026
Size: 94.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for x_iztro-0.1.1.tar.gz
Algorithm	Hash digest
SHA256	`9d11a5d9189c25960305c591d526614a5f5c5f5ae4baacff7ae17c19c6eb4940`
MD5	`f8b02cbbbba07c7cd778981b77b6b483`
BLAKE2b-256	`14500a7918326bd261e5707f4c192c3363c504451c315450d9302baf1db65b8b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for x_iztro-0.1.1.tar.gz:

Publisher: wheels.yml on x-haose/x-iztro

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: x_iztro-0.1.1.tar.gz
- Subject digest: 9d11a5d9189c25960305c591d526614a5f5c5f5ae4baacff7ae17c19c6eb4940
- Sigstore transparency entry: 2436054327
- Sigstore integration time: Aug 12, 2026
Source repository:
- Permalink: x-haose/x-iztro@78cdb0bf05e3d67dc2b289effcd56c2b6c8dba81
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/x-haose
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: wheels.yml@78cdb0bf05e3d67dc2b289effcd56c2b6c8dba81
- Trigger Event: push

File details

Details for the file x_iztro-0.1.1-cp310-abi3-win_amd64.whl.

File metadata

Download URL: x_iztro-0.1.1-cp310-abi3-win_amd64.whl
Upload date: Aug 12, 2026
Size: 417.6 kB
Tags: CPython 3.10+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for x_iztro-0.1.1-cp310-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`b69f7eba88c7325d41cf2051637140af2c1ef65c9b17939f8ae26e4e841df896`
MD5	`8ec84224b8aaf42408b7c3cf11773d37`
BLAKE2b-256	`2a1e6d242e7b2b5a2c953312291196ab18b98214cc1cc09eddf06303c792c5b3`

See more details on using hashes here.

Provenance

The following attestation bundles were made for x_iztro-0.1.1-cp310-abi3-win_amd64.whl:

Publisher: wheels.yml on x-haose/x-iztro

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: x_iztro-0.1.1-cp310-abi3-win_amd64.whl
- Subject digest: b69f7eba88c7325d41cf2051637140af2c1ef65c9b17939f8ae26e4e841df896
- Sigstore transparency entry: 2436056779
- Sigstore integration time: Aug 12, 2026
Source repository:
- Permalink: x-haose/x-iztro@78cdb0bf05e3d67dc2b289effcd56c2b6c8dba81
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/x-haose
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: wheels.yml@78cdb0bf05e3d67dc2b289effcd56c2b6c8dba81
- Trigger Event: push

File details

Details for the file x_iztro-0.1.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: x_iztro-0.1.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Aug 12, 2026
Size: 606.4 kB
Tags: CPython 3.10+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for x_iztro-0.1.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`8bc84e4afda8a1ab924d5687773f26659e3692d7ce0f28f286b21b6b8740c7db`
MD5	`419915f1ea2c9fac3d0b2105fdb74454`
BLAKE2b-256	`6435dc91e7603e3767aefe38af40e324bbcf367ff7e0cae7003c81853c7b869b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for x_iztro-0.1.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on x-haose/x-iztro

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: x_iztro-0.1.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: 8bc84e4afda8a1ab924d5687773f26659e3692d7ce0f28f286b21b6b8740c7db
- Sigstore transparency entry: 2436055600
- Sigstore integration time: Aug 12, 2026
Source repository:
- Permalink: x-haose/x-iztro@78cdb0bf05e3d67dc2b289effcd56c2b6c8dba81
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/x-haose
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: wheels.yml@78cdb0bf05e3d67dc2b289effcd56c2b6c8dba81
- Trigger Event: push

File details

Details for the file x_iztro-0.1.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

Download URL: x_iztro-0.1.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Aug 12, 2026
Size: 580.4 kB
Tags: CPython 3.10+, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for x_iztro-0.1.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`9e0ed9061ef35aed5d03b8e9041395f41b603531f40d283f09411b7953234f9c`
MD5	`6d24a006a0b13117645859d634905a11`
BLAKE2b-256	`c98e0409409213f2a5cb57ab78d1eafd7d5678e16f7766e5bbec21d15e7960c6`

See more details on using hashes here.

Provenance

The following attestation bundles were made for x_iztro-0.1.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: wheels.yml on x-haose/x-iztro

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: x_iztro-0.1.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: 9e0ed9061ef35aed5d03b8e9041395f41b603531f40d283f09411b7953234f9c
- Sigstore transparency entry: 2436054929
- Sigstore integration time: Aug 12, 2026
Source repository:
- Permalink: x-haose/x-iztro@78cdb0bf05e3d67dc2b289effcd56c2b6c8dba81
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/x-haose
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: wheels.yml@78cdb0bf05e3d67dc2b289effcd56c2b6c8dba81
- Trigger Event: push

File details

Details for the file x_iztro-0.1.1-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

Download URL: x_iztro-0.1.1-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Upload date: Aug 12, 2026
Size: 1.0 MB
Tags: CPython 3.10+, macOS 10.12+ universal2 (ARM64, x86-64), macOS 10.12+ x86-64, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for x_iztro-0.1.1-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm	Hash digest
SHA256	`46dddb5ec6933925fd7895b4589c221578bdb0166cc9df770514a1916ce443e1`
MD5	`f28bda366e1996e337c409ead48c0a31`
BLAKE2b-256	`4efe1399f4652131c9ce22cc8a96bbe0375edde99108a15229a431820dfbb70c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for x_iztro-0.1.1-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl:

Publisher: wheels.yml on x-haose/x-iztro

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: x_iztro-0.1.1-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
- Subject digest: 46dddb5ec6933925fd7895b4589c221578bdb0166cc9df770514a1916ce443e1
- Sigstore transparency entry: 2436056182
- Sigstore integration time: Aug 12, 2026
Source repository:
- Permalink: x-haose/x-iztro@78cdb0bf05e3d67dc2b289effcd56c2b6c8dba81
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/x-haose
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: wheels.yml@78cdb0bf05e3d67dc2b289effcd56c2b6c8dba81
- Trigger Event: push

Release history Release notifications | RSS feed

0.2.0

Aug 18, 2026

This release

0.1.1

Aug 12, 2026

0.1.0

Aug 12, 2026

x-iztro 0.1.1

x-iztro

安装

Rust

Python

Go

快速开始

Rust

Python

Go

错误处理

示例项目

测试

运行测试

金标覆盖矩阵

生成测试基准数据

项目结构

移植说明

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed