astroapi-python/src/astroapi/categories/chinese.py at main · astro-api/astroapi-python · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
"""Chinese astrology category client."""

from __future__ import annotations

from astroapi.categories.base import BaseCategoryClient
from astroapi.types.requests import (
    BaZiRequest,
    ChineseCompatibilityRequest,
    LuckPillarsRequest,
    MingGuaRequest,
    YearlyForecastRequest,
)
from astroapi.types.responses import BaZiResponse, GenericResponse
from astroapi.utils.validators import validate_subject


class ChineseClient(BaseCategoryClient):
    """Client for Chinese astrology endpoints.

    Provides BaZi (Four Pillars) and other Chinese astrology calculations.
    """

    API_PREFIX = "/api/v3/chinese"

    def get_bazi(self, request: BaZiRequest) -> BaZiResponse:
        """Get BaZi (Four Pillars) analysis.

        Args:
            request: BaZi request parameters

        Returns:
            BaZi analysis response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)

        url = self._build_url("bazi")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return BaZiResponse(**data)

    def get_zodiac_sign(self, request: BaZiRequest) -> GenericResponse:
        """Get Chinese zodiac sign.

        Args:
            request: Request with birth data

        Returns:
            Chinese zodiac sign response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)

        url = self._build_url("zodiac-sign")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_element(self, request: BaZiRequest) -> GenericResponse:
        """Get Chinese element.

        Args:
            request: Request with birth data

        Returns:
            Chinese element response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)

        url = self._build_url("element")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_compatibility(self, request: ChineseCompatibilityRequest) -> GenericResponse:
        """Get Chinese compatibility analysis."""
        url = self._build_url("compatibility")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_luck_pillars(self, request: LuckPillarsRequest) -> GenericResponse:
        """Get luck pillars analysis."""
        url = self._build_url("luck-pillars")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_ming_gua(self, request: MingGuaRequest) -> GenericResponse:
        """Get Ming Gua calculation."""
        validate_subject(request.subject)
        url = self._build_url("ming-gua")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_yearly_forecast(self, request: YearlyForecastRequest) -> GenericResponse:
        """Get yearly forecast."""
        url = self._build_url("yearly-forecast")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_solar_terms(self, year: int, language: str | None = None) -> GenericResponse:
        """Get solar terms for a year."""
        params = {}
        if language:
            params["language"] = language
        url = self._build_url("calendar", "solar-terms", str(year))
        data = self._http.get(url, params=params if params else None)
        return GenericResponse(**data)

    def get_year_elements(self, year: int, language: str | None = None) -> GenericResponse:
        """Get element balance for a year."""
        params = {}
        if language:
            params["language"] = language
        url = self._build_url("elements", "balance", str(year))
        data = self._http.get(url, params=params if params else None)
        return GenericResponse(**data)

    def get_zodiac_info(self, animal: str, language: str | None = None) -> GenericResponse:
        """Get zodiac animal info."""
        params = {}
        if language:
            params["language"] = language
        url = self._build_url("zodiac", animal)
        data = self._http.get(url, params=params if params else None)
        return GenericResponse(**data)