astroapi-python/src/astroapi/categories/lunar.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
"""Lunar category client."""

from __future__ import annotations

from astroapi.categories.base import BaseCategoryClient
from astroapi.types.requests import (
    LunarEventsRequest,
    LunarPhasesRequest,
    MoonPhaseRequest,
)
from astroapi.types.responses import GenericResponse, MoonPhaseResponse
from astroapi.utils.validators import validate_datetime_location


class LunarClient(BaseCategoryClient):
    """Client for lunar/moon-related endpoints.

    Provides moon phase, void of course, and other lunar calculations.
    """

    API_PREFIX = "/api/v3/lunar"

    def get_moon_phase(self, request: MoonPhaseRequest) -> MoonPhaseResponse:
        """Get moon phase information.

        Args:
            request: Moon phase request parameters

        Returns:
            Moon phase response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("phase")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return MoonPhaseResponse(**data)

    def get_void_of_course(self, request: MoonPhaseRequest) -> GenericResponse:
        """Get void of course moon periods.

        Args:
            request: Request with date parameters

        Returns:
            Void of course periods response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("void-of-course")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_lunar_mansions(self, request: MoonPhaseRequest) -> GenericResponse:
        """Get lunar mansion information.

        Args:
            request: Request with date parameters

        Returns:
            Lunar mansions response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("mansions")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_phases(self, request: LunarPhasesRequest) -> GenericResponse:
        """Get precise lunar phases."""
        validate_datetime_location(request.datetime_location)
        url = self._build_url("phases")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_events(self, request: LunarEventsRequest) -> GenericResponse:
        """Get special lunar events."""
        validate_datetime_location(request.datetime_location)
        url = self._build_url("events")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

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