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

from __future__ import annotations

from astroapi.categories.base import BaseCategoryClient
from astroapi.types.requests import (
    EclipseInterpretationRequest,
    EclipseNatalCheckRequest,
    EclipsesRequest,
)
from astroapi.types.responses import EclipsesResponse, GenericResponse
from astroapi.utils.validators import validate_subject


class EclipsesClient(BaseCategoryClient):
    """Client for eclipse endpoints.

    Provides solar and lunar eclipse calculations for date ranges.
    """

    API_PREFIX = "/api/v3/eclipses"

    def get_eclipses(self, request: EclipsesRequest) -> EclipsesResponse:
        """Get eclipses in a date range.

        Args:
            request: Eclipses request parameters

        Returns:
            Eclipses list response

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

    def get_solar_eclipses(self, request: EclipsesRequest) -> EclipsesResponse:
        """Get solar eclipses in a date range.

        Args:
            request: Eclipses request parameters

        Returns:
            Solar eclipses list response

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

    def get_lunar_eclipses(self, request: EclipsesRequest) -> EclipsesResponse:
        """Get lunar eclipses in a date range.

        Args:
            request: Eclipses request parameters

        Returns:
            Lunar eclipses list response

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

    def get_upcoming(self, limit: int | None = None) -> GenericResponse:
        """Get upcoming eclipses."""
        params = {}
        if limit is not None:
            params["limit"] = limit
        url = self._build_url("upcoming")
        data = self._http.get(url, params=params if params else None)
        return GenericResponse(**data)

    def get_natal_check(self, request: EclipseNatalCheckRequest) -> GenericResponse:
        """Check eclipse impact on natal chart."""
        validate_subject(request.subject)
        url = self._build_url("natal-check")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_interpretation(self, request: EclipseInterpretationRequest) -> GenericResponse:
        """Get eclipse interpretation."""
        url = self._build_url("interpretation")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)