How skjpt/bazi works
1. Repository purpose
- This is an offline, command-line Python toolkit for Chinese metaphysics calculations: 八字排盘 (bazi), 罗喉日时 (luohou), and 生肖合婚 (shengxiao).
- The repo is not a web service or library package with a central API; it is a set of standalone CLI utilities sharing a common calculation and rule-data layer.
2. Main entrypoints
- bazi.py is the primary entrypoint and the most complex application.
- luohou.py computes “罗喉日时” for date-based warnings.
- shengxiao.py maps a user’s zodiac sign to compatibility/conflict relationships.
- These scripts are separate top-level executables, each focused on a different user-facing calculation.
3. Shared calculation core
- ganzhi.py appears to provide the Heavenly Stems / Earthly Branches logic and sexagenary-cycle utilities.
- sizi.py likely models the “four pillars” structure and related derived values used by bazi.py.
- shen.py likely contains the “神煞” logic and lookup rules used to annotate charts with auspicious/inauspicious indicators.
- shengxiao.py and luohou.py also depend on the same stem/branch foundation rather than reimplementing calendrical rules.
4. Shared helpers and rule tables
- common.py is the shared utility layer for formatting, grouping, and reusable computations.
- datas.py likely holds the static datasets: mappings, lookup tables, compatibility relations, and precomputed metaphysical rules.
- These modules are the main “knowledge base” of the application: the outputs are driven more by tables/rules than by complex business logic.
5. Calendar and lunar conversion dependency
- The repo depends on sxtwl for calendar conversion and lunar/solar date calculations, which is critical to all tools that need accurate date-to-pillar mapping.
- bidict is also required, likely to support reversible symbol/name mappings.
- This external calendar library is a key architectural boundary: the repo’s metaphysics logic sits on top of an imported date-calculation engine.
6. bazi.py subsystem
- bazi.py orchestrates input parsing, calendar conversion, pillar generation, relationship analysis, five-element scoring, and textual interpretation.
- Its output combines several layers: raw four pillars, stem/branch interactions, 五行分数, 格局判断, 神煞, and quoted textual judgments.
- It is the composition layer that pulls together almost all shared modules into one report.
7. luohou.py subsystem
- luohou.py is a specialized date/time calculator that prints day-by-day warnings about “杀师时”.
- It likely uses calendar conversion plus a rule table for mapping dates/times to prohibited periods.
- Compared with bazi.py, it is narrower and mostly a formatter over a lookup-driven computation.
8. shengxiao.py subsystem
- shengxiao.py accepts a zodiac animal as input and returns compatibility, clash, punishment, harm, and break relationships.
- The data flow is simple: zodiac input → branch mapping → static compatibility tables → human-readable output.
- It is essentially a deterministic lookup tool with light normalization and formatting.
9. Reference books and textual interpretations
- books/ contains markdown versions of classical metaphysics texts.
- The README examples show long judgment passages and historical formula text being emitted in bazi.py, so these books likely serve as source material or embedded references for interpretation output.
- This repo therefore has a “knowledge corpus” boundary separate from the executable code.
10. Examples and documentation
- examples/ contains markdown examples demonstrating specific chart types or interpretation cases.
- README.md is both user guide and product description, including sample terminal output and dependency notes.
- These files are not runtime dependencies, but they are important for understanding expected output shape and manual verification.
11. Conversion / preprocessing path
- convert.py is likely a utility for transforming source text or structured rules into the markdown/data format used by the repo.
- Architecturally, this suggests a build/preparation step for maintaining the reference corpus and lookup data, even if the main tools run directly from source.
- The runtime tools and the content-preparation script are separated.
12. Overall boundary map
- Input boundary: CLI arguments in the three top-level scripts.
- Core boundary: shared calendrical/stem-branch logic plus lookup tables in common.py, datas.py, ganzhi.py, shen.py, and sizi.py.
- External boundary: sxtwl for lunar/solar calendar conversion.
- Output boundary: formatted terminal reports and markdown reference material.
13. Diagram takeaway
- If you draw the architecture, show one central shared domain layer feeding three independent CLI tools.
- Under the shared layer, emphasize static rule/data modules and the imported calendar library.
- Around that, show documentation/reference books as supporting content, not as runtime services.
Main entry points: bazi.py bazi.py · luohou.py luohou.py · shengxiao.py shengxiao.py · ganzhi.py ganzhi.py
Components 14
CLI tools
Standalone command-line entrypoints for the three user-facing calculators.
- bazi.py · Main 八字排盘 command; orchestrates chart generation, scoring, rules, and interpretations.
bazi.py - luohou.py · Computes 罗喉日时 warnings from dates and times.
luohou.py - shengxiao.py · Maps生肖 inputs to compatibility, clash, punishment, harm, and break relationships.
shengxiao.py
Shared core
Calendrical, stem-branch, and rule-data modules reused across tools.
- common.py · Formatting and reusable utilities shared by the calculators.
common.py - datas.py · Static mappings, lookup tables, and metaphysics datasets.
datas.py - ganzhi.py · Heavenly stems, earthly branches, and sexagenary-cycle utilities.
ganzhi.py - sizi.py · Four-pillars model and derived values used by bazi calculations.
sizi.py - shen.py · Auspicious/inauspicious indicator logic used to annotate charts.
shen.py
Reference content
Classical texts, examples, and documentation supporting interpretation and maintenance.
- convert.py · Preprocessing utility for transforming source material or rules into repo formats.
convert.py - books · Markdown source texts used as reference material for interpretations.
books - examples · Markdown examples showing chart and interpretation cases.
examples - README.md · User guide, examples, and dependency notes for the toolkit.
README.md
External deps
Imported libraries that provide calendar conversion and reversible mappings.
- sxtwl · External lunar/solar calendar and date-conversion engine.
- bidict · External reversible mapping helper used for symbol/name conversions.
Connections 22
- bazi.py → common.py: formats with · Shares output formatting and reusable helpers.
- bazi.py → datas.py: looks up rules · Consumes static rule tables and domain data.
- bazi.py → ganzhi.py: builds pillars · Uses stem-branch and cycle utilities.
- bazi.py → sizi.py: models chart · Constructs the four-pillars structure.
- bazi.py → shen.py: annotates chart · Adds神煞 and related indicators.
- bazi.py → sxtwl: converts date · Depends on calendar conversion for accurate pillar mapping.
- luohou.py → common.py: formats with · Uses shared helpers for presentation.
- luohou.py → datas.py: looks up rules · Uses date/time prohibition tables.
- luohou.py → ganzhi.py: maps cycles · Relies on stem-branch/date-cycle logic.
- luohou.py → sxtwl: converts date · Uses calendar conversion to derive day/time context.
- shengxiao.py → common.py: formats with · Uses shared helpers for normalization and output.
- shengxiao.py → datas.py: looks up relations · Reads compatibility and conflict tables.
- shengxiao.py → ganzhi.py: normalizes zodiac · Uses branch-based zodiac foundations.
- ganzhi.py → bidict: uses mapping · External reversible mapping support.
- convert.py → datas.py: prepares data · Transforms source material into repository lookup formats.
- convert.py → books: derives from · May consume classical texts while preparing structured data.
- convert.py → examples: validates against · Uses examples as reference cases for prepared outputs.
- README.md → bazi.py: documents · Describes the primary CLI workflow and sample output.
- README.md → luohou.py: documents · Explains the warning calculator usage.
- README.md → shengxiao.py: documents · Explains the zodiac compatibility tool.
- books → shen.py: source material · Classical texts inform interpretation rules and judgments.
- examples → bazi.py: shows output · Illustrates expected chart and interpretation shapes.