glossary.py

"""Glossary category client for reference data."""

from __future__ import annotations

from astroapi.categories.base import BaseCategoryClient
from astroapi.types.responses import GlossaryResponse


class GlossaryClient(BaseCategoryClient):
    """Client for glossary and reference data endpoints.

    Provides access to cities, house systems, zodiac signs, planets, aspects,
    keywords, and other reference data.
    """

    API_PREFIX = "/api/v3/glossary"

    def get_cities(self, query: str | None = None, limit: int = 100) -> GlossaryResponse:
        """Search for cities.

        Args:
            query: Search query (optional)
            limit: Maximum number of results

        Returns:
            Cities list response

        Raises:
            AstrologyError: If API request fails
        """
        params: dict[str, str | int] = {}
        if query:
            params["q"] = query
        params["limit"] = limit

        url = self._build_url("cities")
        data = self._http.get(url, params=params)
        return GlossaryResponse(**data)

    def get_house_systems(self) -> GlossaryResponse:
        """Get list of available house systems.

        Returns:
            House systems list response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("house-systems")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_zodiac_signs(self) -> GlossaryResponse:
        """Get list of zodiac signs.

        Returns:
            Zodiac signs list response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("zodiac-signs")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_planets(self) -> GlossaryResponse:
        """Get list of planets and points.

        Returns:
            Planets list response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("planets")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_aspects(self) -> GlossaryResponse:
        """Get list of aspects.

        Returns:
            Aspects list response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("aspects")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_keywords(self, category: str | None = None) -> GlossaryResponse:
        """Get astrological keywords.

        Args:
            category: Filter by category (optional)

        Returns:
            Keywords list response

        Raises:
            AstrologyError: If API request fails
        """
        params = {}
        if category:
            params["category"] = category

        url = self._build_url("keywords")
        data = self._http.get(url, params=params if params else None)
        return GlossaryResponse(**data)

    def get_fixed_stars(self) -> GlossaryResponse:
        """Get list of fixed stars.

        Returns:
            Fixed stars list response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("fixed-stars")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_asteroids(self) -> GlossaryResponse:
        """Get list of asteroids.

        Returns:
            Asteroids list response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("asteroids")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_arabic_parts(self) -> GlossaryResponse:
        """Get list of Arabic parts.

        Returns:
            Arabic parts list response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("arabic-parts")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_themes(self) -> GlossaryResponse:
        """Get list of astrological themes.

        Returns:
            Themes list response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("themes")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_countries(self) -> GlossaryResponse:
        """Get list of countries."""
        url = self._build_url("countries")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_active_points(self) -> GlossaryResponse:
        """Get list of active points."""
        url = self._build_url("active-points")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_primary_active_points(self) -> GlossaryResponse:
        """Get list of primary active points."""
        url = self._build_url("active-points", "primary")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_zodiac_types(self) -> GlossaryResponse:
        """Get list of zodiac types."""
        url = self._build_url("zodiac-types")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_languages(self) -> GlossaryResponse:
        """Get list of supported languages."""
        url = self._build_url("languages")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_houses(self) -> GlossaryResponse:
        """Get list of astrological houses."""
        url = self._build_url("houses")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_elements(self) -> GlossaryResponse:
        """Get list of elements."""
        url = self._build_url("elements")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_life_areas(self) -> GlossaryResponse:
        """Get list of life areas."""
        url = self._build_url("life-areas")
        data = self._http.get(url)
        return GlossaryResponse(**data)

    def get_horary_categories(self) -> GlossaryResponse:
        """Get list of horary categories."""
        url = self._build_url("horary-categories")
        data = self._http.get(url)
        return GlossaryResponse(**data)