Lightweight queries

Some questions do not need a whole chart. These five functions each run only as far as necessary and return; their results always agree with the corresponding fields of a full chart, because they go through the same core logic.

from x_iztro import query

get_zodiac_by_solar_date

Purpose Get the Chinese zodiac animal from a solar date.

Zi Wei meaning The zodiac animal is determined by the year branch, and when the year branch turns over is governed by year_divide. For someone born between lunar New Year and the Beginning of Spring, the two settings give different animals — not a defect, a difference of school.

Signature

def get_zodiac_by_solar_date(
    solar_date: str,
    language: LanguageType = "zh-CN",
    config: ChartConfig | None = None,
) -> str

Parameters

Return value str — the animal name translated into the language.

Example

print(query.get_zodiac_by_solar_date("2000-8-16", language="en-US"))

Output

dragon

Edge cases and pitfalls

get_sign_by_solar_date / get_sign_by_lunar_date

Purpose Get the zodiac sign.

Zi Wei meaning The zodiac sign is a Western astrology concept determined solely by the solar date, unrelated to the Zi Wei algorithm. The lunar version converts to solar first, so both give the same result for the same day.

Signature

def get_sign_by_solar_date(solar_date: str, language: LanguageType = "zh-CN") -> str
def get_sign_by_lunar_date(
    lunar_date: str,
    is_leap_month: bool = False,
    language: LanguageType = "zh-CN",
) -> str

Parameters

There is no config parameter — zodiac signs are unaffected by any setting.

Return value str.

Example

print(query.get_sign_by_solar_date("2000-8-16", language="en-US"))
print(query.get_sign_by_lunar_date("2000-7-17", language="en-US"))

Output

leo
leo

get_major_star_by_solar_date / get_major_star_by_lunar_date

Purpose Get just the Soul palace's major stars, without charting the whole thing.

Zi Wei meaning The major stars of the Soul palace are the single most commonly asked item in Zi Wei Dou Shu. When the Soul palace is empty, convention borrows the major stars of the opposite palace, and this function already handles that step.

Signature

def get_major_star_by_solar_date(
    solar_date: str,
    time_index: TimeIndexType,
    *,
    fix_leap: bool = True,
    language: LanguageType = "zh-CN",
    config: ChartConfig | None = None,
) -> str

def get_major_star_by_lunar_date(
    lunar_date: str,
    time_index: TimeIndexType,
    *,
    is_leap_month: bool = False,
    fix_leap: bool = True,
    language: LanguageType = "zh-CN",
    config: ChartConfig | None = None,
) -> str

Parameters

Return value str — several major stars separated by commas; the opposite palace's major stars when the Soul palace is empty.

Example

print(query.get_major_star_by_solar_date("2000-8-16", 2, language="en-US"))
print(query.get_major_star_by_solar_date("2000-8-16", 2, language="zh-CN"))

Output

emperor
紫微

Edge cases and pitfalls

get_major_star_keys_by_solar_date / get_major_star_keys_by_lunar_date

Purpose The Soul palace's major stars as language-independent keys — the key form of the two functions above, for programmatic checks.

Signature

def get_major_star_keys_by_solar_date(
    solar_date: str,
    time_index: TimeIndexType,
    *,
    fix_leap: bool = True,
    config: ChartConfig | None = None,
) -> list[str]

def get_major_star_keys_by_lunar_date(
    lunar_date: str,
    time_index: TimeIndexType,
    *,
    is_leap_month: bool = False,
    fix_leap: bool = True,
    config: ChartConfig | None = None,
) -> list[str]

Return value list[str] — keys from the MajorStar enum's domain (e.g. "ziweiMaj"); an empty Soul palace borrows its opposite's major stars just the same. Keys are language-independent, so these functions take no language.

Example

print(query.get_major_star_keys_by_solar_date("2000-8-16", 2))

Output

['ziweiMaj']