py-iztro

https://github.com/x-haose/py-iztro
Admin
py-iztro is a Python version of the renowned Ziwei Doushu (Purple Star Astrology) charting tool...
Tokens:6,256
Snippets:26
Trust Score:7.9
Update:8 months ago
Show doc for...
Tokens:
Raw
### Generate Natal Chart by Solar Calendar using py-iztro

Source: https://context7.com/x-haose/py-iztro/llms.txt

This example shows how to generate a natal chart using the solar calendar with the py-iztro library. It involves creating an `Astro` instance and then calling the `by_solar` method with the birth date and gender. This is a common pattern for initializing astrological calculations.

```python
from pyiztro.astro import Astro

astro = Astro()
chart = astro.by_solar(date="2000-08-16", gender=2)
```

--------------------------------

### Complete Py-iZtro Workflow: Chart Generation to JSON Export

Source: https://context7.com/x-haose/py-iztro/llms.txt

A comprehensive Python example demonstrating the full lifecycle of using py-iztro: initializing the Astro object, optionally configuring calculation methods, generating a birth chart, accessing key palace data, calculating current horoscopes, and exporting the entire chart data as a JSON string. This function is designed for detailed astrological analysis.

```python
from py_iztro import Astro
from py_iztro.core.models import ConfigModel, YearDivideEnum

def analyze_birth_chart(birth_date: str, time_index: int, gender: str):
    """Complete Zi Wei Dou Shu analysis workflow."""

    # Initialize
    astro = Astro()

    # Optional: Configure calculation method
    config = ConfigModel(year_divide=YearDivideEnum.EXACT)
    astro.config(config)

    # Generate birth chart
    chart = astro.by_solar(birth_date, time_index, gender)

    # Print basic info
    print("=" * 50)
    print(f"Birth Chart for {chart.solar_date} ({chart.lunar_date})")
    print(f"Time: {chart.time} ({chart.time_range})")
    print(f"Zodiac: {chart.sign} | Chinese Zodiac: {chart.zodiac}")
    print(f"Five Elements: {chart.five_elements_class}")
    print(f"Soul: {chart.soul} | Body: {chart.body}")
    print("=" * 50)

    # Find and display key palaces
    for palace in chart.palaces:
        if palace.name in ["命宫", "财帛", "官禄", "夫妻"]:
            stars = ", ".join([f"{s.name}({s.brightness or ''})" for s in palace.major_stars])
            print(f"{palace.name}: {stars or 'No major stars'}")

    # Calculate current fortune
    print("\n--- Current Fortune (2025-01-01) ---")
    horoscope = chart.horoscope("2025-01-01")
    print(f"Decade: {horoscope.decadal.heavenly_stem}{horoscope.decadal.earthly_branch}")
    print(f"Yearly: {horoscope.yearly.heavenly_stem}{horoscope.yearly.earthly_branch}")
    print(f"Mutagen Stars: {horoscope.yearly.mutagen}")

    # Export complete data
    return chart.model_dump_json(by_alias=True, indent=2)
```

--------------------------------

### Configure and Get Zi Wei Calculation Parameters (Python)

Source: https://context7.com/x-haose/py-iztro/llms.txt

Shows how to use the `config()` and `get_config()` methods of the `Astro` class to customize Zi Wei calculation parameters. This includes setting mutagen tables, star brightness, year/age division methods, and calculation algorithms. It demonstrates retrieving the current configuration, creating a custom configuration model, applying it, and verifying the changes.

```python
from py_iztro import Astro
from py_iztro.core.models import ConfigModel, YearDivideEnum, AgeDivideEnum, AlgorithmEnum

astro = Astro()

# Get current configuration
current_config = astro.get_config()
print(f"Current config: {current_config.model_dump_json(indent=4)}")

# Create custom configuration
custom_config = ConfigModel(
    # Custom mutagen table - override specific stems
    mutagens={
        "庚": ["太阳", "武曲", "天同", "天相"]
    },
    # Custom brightness table - set brightness for all 12 palaces
    brightness={
        "贪狼": ["旺", "旺", "旺", "旺", "旺", "旺", "旺", "旺", "旺", "旺", "旺", "旺"]
    },
    # Year division: "normal" (lunar new year) or "exact" (li chun)
    year_divide=YearDivideEnum.EXACT,
    # Age division: "normal" (year only) or "birthday" (birthday boundary)
    age_divide=AgeDivideEnum.BIRTHDAY,
    # Horoscope division point
    horoscope_divide=YearDivideEnum.NORMAL,
    # Algorithm: "default" (Zi Wei Quan Shu) or "zhongzhou" (Zhongzhou school)
    algorithm=AlgorithmEnum.ZHONGZHOU
)

# Apply configurationastro.config(custom_config)

# Verify configuration was applied
updated_config = astro.get_config()
print(f"Updated config: {updated_config.model_dump_json(indent=4)}")

# Generate chart with new configuration
chart = astro.by_solar("2000-8-16", 2, "女")

```

--------------------------------

### Serialize Chart Data to JSON using py-iztro

Source: https://context7.com/x-haose/py-iztro/llms.txt

This example shows how to serialize the generated chart data into JSON format using the `model_dump_json()` method provided by py-iztro's Pydantic models. This is crucial for integrating the astrological data with web APIs or for persistent storage.

```python
from pyiztro.astro import Astro

astro = Astro()
chart = astro.by_solar(date="2000-08-16", gender=2)
json_output = chart.model_dump_json()
```

--------------------------------

### Initialize Astro Class and Generate Chart (Python)

Source: https://context7.com/x-haose/py-iztro/llms.txt

Demonstrates the main entry point for generating Zi Wei Dou Shu charts using the Astro class. It initializes the calculator and generates a chart from a solar date, printing key details of the resulting chart object.

```python
from py_iztro import Astro

# Initialize the Astro calculator
astro = Astro()

# Generate a chart - this is the main entry point for all calculations
chart = astro.by_solar("2000-8-16", 2, "女")
print(f"Gender: {chart.gender}")
print(f"Solar Date: {chart.solar_date}")
print(f"Lunar Date: {chart.lunar_date}")
print(f"Chinese Date: {chart.chinese_date}")
print(f"Time Period: {chart.time} ({chart.time_range})")
print(f"Zodiac Sign: {chart.sign}")
print(f"Chinese Zodiac: {chart.zodiac}")
print(f"Five Elements Class: {chart.five_elements_class}")
print(f"Soul Star: {chart.soul}")
print(f"Body Star: {chart.body}")
```

--------------------------------

### Accessing Palace and Star Data in Py-iZtro

Source: https://context7.com/x-haose/py-iztro/llms.txt

Demonstrates how to retrieve and display detailed information about a specific palace within a Zi Wei chart, including its major stars, minor stars, adjective stars, and fortune indicators. Requires the py_iztro library.

```python
from py_iztro import Astro
from py_iztro.core.models import PalaceModel, StarModel

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

# Get a specific palace (e.g., Ming Gong - Life Palace, usually index 4)
life_palace: PalaceModel = chart.palaces[4]

print(f"=== {life_palace.name} ===")
print(f"Index: {life_palace.index}")
print(f"Heavenly Stem: {life_palace.heavenly_stem}")
print(f"Earthly Branch: {life_palace.earthly_branch}")
print(f"Is Body Palace: {life_palace.is_body_palace}")
print(f"Is Original Palace (Lai Yin): {life_palace.is_original_palace}")

# Major Stars (主星)
print("\nMajor Stars:")
for star in life_palace.major_stars:
    print(f"  {star.name}")
    print(f"    Type: {star.type}")  # "major", "soft", "tough", etc.
    print(f"    Scope: {star.scope}")  # "origin", "decadal", "yearly"
    print(f"    Brightness: {star.brightness}")  # 庙, 旺, 得, 利, 平, 不, 陷
    print(f"    Mutagen: {star.mutagen}")  # 禄, 权, 科, 忌 or None

# Minor Stars (辅星) - helper and malefic stars
print("\nMinor Stars:")
for star in life_palace.minor_stars:
    print(f"  {star.name} ({star.type})")

# Adjective Stars (杂耀)
print("\nAdjective Stars:")
for star in life_palace.adjective_stars:
    print(f"  {star.name}")

# 12 Gods positions
print(f"\nChang Sheng 12: {life_palace.changsheng12}")
print(f"Bo Shi 12: {life_palace.boshi12}")
print(f"Jiang Qian 12: {life_palace.jiangqian12}")
print(f"Sui Qian 12: {life_palace.suiqian12}")

# Decade fortune info
print(f"\nDecade Fortune Range: {life_palace.decadal.range}")
print(f"Decade Stem-Branch: {life_palace.decadal.heavenly_stem}{life_palace.decadal.earthly_branch}")

# Small fortune ages
print(f"Small Fortune Ages: {life_palace.ages}")
```

--------------------------------

### Py-iZtro Multi-Language Support for Chart Output

Source: https://context7.com/x-haose/py-iztro/llms.txt

Illustrates how to generate Zi Wei charts in various languages supported by py-iztro, including Chinese (Simplified/Traditional), English, Japanese, Korean, and Vietnamese. The 'language' parameter in the `astro.by_solar` method controls the output language.

```python
from py_iztro import Astro

astro = Astro()

# Supported languages: "zh-CN", "zh-TW", "en-US", "ja-JP", "ko-KR", "vi-VN"

# Chinese Simplified (default)
chart_cn = astro.by_solar("2000-8-16", 2, "女", language="zh-CN")
print(f"Chinese (Simplified): {chart_cn.palaces[0].name}")

# Chinese Traditional
chart_tw = astro.by_solar("2000-8-16", 2, "女", language="zh-TW")
print(f"Chinese (Traditional): {chart_tw.palaces[0].name}")

# English
chart_en = astro.by_solar("2000-8-16", 2, "女", language="en-US")
print(f"English: {chart_en.palaces[0].name}")

# Japanese
chart_ja = astro.by_solar("2000-8-16", 2, "女", language="ja-JP")
print(f"Japanese: {chart_ja.palaces[0].name}")

# Korean
chart_ko = astro.by_solar("2000-8-16", 2, "女", language="ko-KR")
print(f"Korean: {chart_ko.palaces[0].name}")

# Vietnamese
chart_vi = astro.by_solar("2000-8-16", 2, "女", language="vi-VN")
print(f"Vietnamese: {chart_vi.palaces[0].name}")
```

--------------------------------

### AstrolabeModel: Chart Data Structure and Access (Python)

Source: https://context7.com/x-haose/py-iztro/llms.txt

Explains the `AstrolabeModel`, the primary data structure returned by chart generation methods in `py-iztro`. It details how to access basic birth information, soul/body palace details, and iterate through all twelve palaces to inspect their properties, including major/minor stars and decade fortune ranges. The model utilizes Pydantic for validation and JSON serialization.

```python
from py_iztro import Astro, AstrolabeModel

astro = Astro()
chart: AstrolabeModel = astro.by_solar("2000-8-16", 2, "女")

# Basic birth information
print(f"Gender: {chart.gender}")
print(f"Solar Date: {chart.solar_date}")
print(f"Lunar Date: {chart.lunar_date}")
print(f"Chinese Date (Stems & Branches): {chart.chinese_date}")
print(f"Birth Hour: {chart.time} ({chart.time_range})")
print(f"Western Zodiac: {chart.sign}")
print(f"Chinese Zodiac: {chart.zodiac}")

# Soul and Body palace information
print(f"\nSoul Palace Branch: {chart.earthly_branch_of_soul_palace}")
print(f"Body Palace Branch: {chart.earthly_branch_of_body_palace}")
print(f"Soul Lord Star: {chart.soul}")
print(f"Body Lord Star: {chart.body}")
print(f"Five Elements Class: {chart.five_elements_class}")

# Iterate through all 12 palaces
print("\n=== Twelve Palaces ===")
for palace in chart.palaces:
    print(f"\n{palace.name} Palace (Index: {palace.index})")
    print(f"  Stem-Branch: {palace.heavenly_stem}{palace.earthly_branch}")
    print(f"  Is Body Palace: {palace.is_body_palace}")
    print(f"  Is Original Palace: {palace.is_original_palace}")

    # Stars in this palace
    if palace.major_stars:
        for star in palace.major_stars:
            mutagen_info = f" [{star.mutagen}]" if star.mutagen else ""
            brightness_info = f" ({star.brightness})" if star.brightness else ""
            print(f"  Major Star: {star.name}{brightness_info}{mutagen_info}")

    if palace.minor_stars:
        print(f"  Minor Stars: {[s.name for s in palace.minor_stars]}")

    # Decade fortune range
    print(f"  Decade Range: Age {palace.decadal.range[0]}-{palace.decadal.range[1]}")
    print(f"  Small Fortune Ages: {palace.ages[:5]}...")  # First 5 ages

```

--------------------------------

### Generate Chart from Solar Date (Python)

Source: https://context7.com/x-haose/py-iztro/llms.txt

Shows how to generate a Zi Wei Dou Shu astrolabe chart using a solar (Gregorian) calendar date. It details the parameters for `by_solar()`, including date format, time index, gender, and language, and demonstrates exporting the chart as JSON and accessing palace data.

```python
from py_iztro import Astro

astro = Astro()

# Parameters:
# - solar_date_str: Date in "YYYY-M-D" format
# - time_index: Birth hour (0=early zi, 1=chou, 2=yin, 3=mao, 4=chen, 5=si,
#               6=wu, 7=wei, 8=shen, 9=you, 10=xu, 11=hai, 12=late zi)
# - gender: "男" (male) or "女" (female)
# - fix_leap: Adjust leap month calculation (default: True)
# - language: Output language (default: "zh-CN")

# Basic usage
chart = astro.by_solar("2000-8-16", 2, "女")

# With English output
chart_en = astro.by_solar("1990-5-20", 6, "男", language="en-US")

# Export as JSON
json_output = chart.model_dump_json(by_alias=True, indent=4)
print(json_output)

# Access palace data (12 palaces)
for palace in chart.palaces:
    print(f"Palace: {palace.name}")
    print(f"  Heavenly Stem: {palace.heavenly_stem}")
    print(f"  Earthly Branch: {palace.earthly_branch}")
    print(f"  Major Stars: {[star.name for star in palace.major_stars]}")
    print(f"  Decade Range: {palace.decadal.range}")
```

--------------------------------

### Generate Natal Chart by Lunar Calendar using py-iztro

Source: https://context7.com/x-haose/py-iztro/llms.txt

This snippet illustrates generating a natal chart using the lunar calendar with the py-iztro library. Similar to the solar calendar method, it requires creating an `Astro` instance and then using the `by_lunar` method with the birth date and gender. This is essential for astrological systems that rely on lunar dates.

```python
from pyiztro.astro import Astro

astro = Astro()
chart = astro.by_lunar(date="2000-08-16", gender=2)
```

--------------------------------

### Calculate Fortune Periods using py-iztro

Source: https://context7.com/x-haose/py-iztro/llms.txt

This code demonstrates how to calculate multi-level fortune periods (decade, year, month, day, hour) using the `horoscope` method of the `Astro` class in py-iztro. It takes the generated chart object as input and provides detailed fortune analysis over different time spans.

```python
from pyiztro.astro import Astro

astro = Astro()
chart = astro.by_solar(date="2000-08-16", gender=2)
fortune_analysis = chart.horoscope()
```

--------------------------------

### Analyze Birth Chart using py-iztro

Source: https://context7.com/x-haose/py-iztro/llms.txt

This snippet demonstrates how to perform a birth chart analysis using the `analyze_birth_chart` function from the py-iztro library. It takes birth date, gender, and calendar type as input and returns the analysis result. The output can be printed by uncommenting the provided line.

```python
from pyiztro.chart import analyze_birth_chart

result = analyze_birth_chart("2000-8-16", 2, "女")
# print(result)  # Uncomment to see full JSON output
```

--------------------------------

### Calculate Fortune Periods (Python)

Source: https://context7.com/x-haose/py-iztro/llms.txt

Demonstrates the use of the `horoscope()` method to calculate fortune periods (Da Xian, Liu Nian, etc.) for a given date. This method returns comprehensive data including decade, small, yearly, monthly, daily, and hourly fortune calculations based on an existing chart object.

```python
from py_iztro import Astro

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

# Calculate horoscope for a specific date
horoscope = chart.horoscope("2025-01-01")

# The 'horoscope' object contains detailed fortune period data.
```

--------------------------------

### Access Horoscope Data and Export as JSON

Source: https://context7.com/x-haose/py-iztro/llms.txt

Demonstrates how to access various horoscope details like solar/lunar dates, decade, small, yearly, monthly, and daily fortunes from a horoscope object. It also shows how to export the complete horoscope data as a JSON string.

```python
from py_iztro import Astro

# Assuming 'horoscope' is an initialized Astro object or a horoscope result
# For example:
# astro = Astro()
# horoscope = astro.by_solar("2000-8-16", 2, "女")

# Placeholder for horoscope object for demonstration
class MockHoroscope:
    def __init__(self):
        self.solar_date = "2000-08-16"
        self.lunar_date = "2000-07-17"
        class Decadal:
            index = 1
            name = "紫微"
            heavenly_stem = "甲"
            earthly_branch = "子"
            mutagen = "化科"
        self.decadal = Decadal()
        class Age:
            nominal_age = 24
            palace_names = ["命", "兄", "夫妻", "子女", "财帛", "疾厄", "迁移", "交友", "官禄", "田宅", "福德", "父母"]
        self.age = Age()
        class Yearly:
            heavenly_stem = "庚"
            earthly_branch = "申"
            class YearlyDecStar:
                jiangqian12 = "天马"
            yearly_dec_star = YearlyDecStar()
        self.yearly = Yearly()
        class Monthly:
            index = 5
        self.monthly = Monthly()
        class Daily:
            index = 15
        self.daily = Daily()
        class Hourly:
            index = 9
        self.hourly = Hourly()

    def model_dump_json(self, by_alias=False, indent=None):
        return "{\"solar_date\": \"2000-08-16\", \"lunar_date\": \"2000-07-17\", ...}" # Simplified JSON output

horoscope = MockHoroscope()

# Access horoscope data
print(f"Solar Date: {horoscope.solar_date}")
print(f"Lunar Date: {horoscope.lunar_date}")

# Decade fortune (大限) - 10-year period
print(f"\nDecade Fortune:")
print(f"  Palace Index: {horoscope.decadal.index}")
print(f"  Name: {horoscope.decadal.name}")
print(f"  Heavenly Stem: {horoscope.decadal.heavenly_stem}")
print(f"  Earthly Branch: {horoscope.decadal.earthly_branch}")
print(f"  Mutagen Stars: {horoscope.decadal.mutagen}")

# Small fortune (小限) - age-based
print(f"\nSmall Fortune:")
print(f"  Nominal Age: {horoscope.age.nominal_age}")
print(f"  Palace Names: {horoscope.age.palace_names}")

# Yearly fortune (流年)
print(f"\nYearly Fortune:")
print(f"  Heavenly Stem: {horoscope.yearly.heavenly_stem}")
print(f"  Earthly Branch: {horoscope.yearly.earthly_branch}")
print(f"  Yearly Stars (Jiang Qian 12): {horoscope.yearly.yearly_dec_star.jiangqian12}")

# Monthly and daily fortune
print(f"\nMonthly Fortune Index: {horoscope.monthly.index}")
print(f"Daily Fortune Index: {horoscope.daily.index}")
print(f"Hourly Fortune Index: {horoscope.hourly.index}")

# Export complete horoscope as JSON
json_output = horoscope.model_dump_json(by_alias=True, indent=4)
print(json_output)

```

--------------------------------

### Generate Chart from Lunar Date (Python)

Source: https://context7.com/x-haose/py-iztro/llms.txt

Illustrates how to generate a Zi Wei Dou Shu astrolabe chart using a Chinese lunar calendar date. This method is useful when the birthdate is known in the lunar format. It also shows how to compare results with the `by_solar()` method to confirm equivalence and access specific palace information.

```python
from py_iztro import Astro

astro = Astro()

# Parameters:
# - lunar_date_str: Lunar date in "YYYY-M-D" format (e.g., 2000-7-17 for 7th month 17th day)
# - time_index: Birth hour (0-12)
# - gender: "男" (male) or "女" (female)
# - fix_leap: Adjust leap month calculation (default: True)
# - language: Output language (default: "zh-CN")

# Generate chart using lunar date
chart_lunar = astro.by_lunar("2000-7-17", 2, "女")

# Compare with solar date equivalent
chart_solar = astro.by_solar("2000-8-16", 2, "女")

# These should produce identical results
lunar_json = chart_lunar.model_dump_json(by_alias=True)
solar_json = chart_solar.model_dump_json(by_alias=True)
print(f"Results match: {lunar_json == solar_json}")  # True

# Access specific palace information
ming_gong = chart_lunar.palaces[4]  # Ming Gong (Life Palace)
print(f"Life Palace: {ming_gong.name}")
print(f"Major Stars in Life Palace: {[s.name for s in ming_gong.major_stars]}")
```
Tokens:
Raw