freeastroapi 0.2.0__py3-none-any.whl

freeastroapi/client.py

@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from typing import Any, Generic, TypeVar
+
+import httpx
+
+from ._generated import AsyncGeneratedResources, GeneratedResources
+from .errors import NetworkError, TimeoutError, error_from_response
+from .resources import (
+    AsyncGeoResource,
+    AsyncMoonResource,
+    AsyncSkyEventsResource,
+    AsyncWesternResource,
+    GeoResource,
+    MoonResource,
+    SkyEventsResource,
+    WesternResource,
+)
+
+T = TypeVar("T")
+
+DEFAULT_BASE_URL = "https://api.freeastroapi.com"
+DEFAULT_RETRY_STATUSES = frozenset({408, 429, 500, 502, 503, 504})
+IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+
+@dataclass(frozen=True, slots=True)
+class RetryConfig:
+    retries: int = 2
+    base_delay: float = 0.25
+    max_delay: float = 5.0
+    statuses: frozenset[int] = DEFAULT_RETRY_STATUSES
+
+
+DEFAULT_RETRY = RetryConfig()
+
+
+@dataclass(frozen=True, slots=True)
+class RequestOptions:
+    headers: Mapping[str, str] = field(default_factory=dict)
+    idempotency_key: str | None = None
+    timeout: float | None = None
+    retry: bool | RetryConfig | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SDKResponse(Generic[T]):
+    data: T
+    response: httpx.Response
+
+
+def _retry_after_seconds(response: httpx.Response) -> float | None:
+    value = response.headers.get("retry-after")
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        try:
+            retry_at = parsedate_to_datetime(value)
+            if retry_at.tzinfo is None:
+                retry_at = retry_at.replace(tzinfo=UTC)
+            return max(0.0, (retry_at - datetime.now(UTC)).total_seconds())
+        except (TypeError, ValueError, OverflowError):
+            return None
+
+
+def _response_data(response: httpx.Response) -> Any:
+    if response.status_code == 204:
+        return None
+    content_type = response.headers.get("content-type", "")
+    if "application/json" in content_type or "+json" in content_type:
+        return response.json()
+    return response.text
+
+
+class _ClientSettings:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        retry: RetryConfig | None,
+        headers: Mapping[str, str] | None,
+    ) -> None:
+        if not api_key.strip():
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.retry = retry
+        self.headers = dict(headers or {})
+
+    def request_headers(self, options: RequestOptions) -> dict[str, str]:
+        headers = {key.lower(): value for key, value in {**self.headers, **options.headers}.items()}
+        headers.update({"accept": "application/json", "x-api-key": self.api_key})
+        if options.idempotency_key:
+            headers["idempotency-key"] = options.idempotency_key
+        return headers
+
+    def retry_config(self, method: str, options: RequestOptions) -> RetryConfig | None:
+        if self.retry is None or options.retry is False:
+            return None
+        explicitly_enabled = options.retry is True or isinstance(options.retry, RetryConfig)
+        replay_safe = method in IDEMPOTENT_METHODS or bool(options.idempotency_key)
+        if not explicitly_enabled and not replay_safe:
+            return None
+        return options.retry if isinstance(options.retry, RetryConfig) else self.retry
+
+
+class FreeAstro(GeneratedResources):
+    """FreeAstroAPI client.
+
+    Resources follow the API paths: ``client.western.natal.insights(...)`` calls
+    ``POST /api/v1/western/natal/insights``. Where an operation exists in several API versions,
+    the plain method name calls the latest one and older ones carry a suffix
+    (``client.vedic.chart`` is v2, ``client.vedic.chart_v1`` is v1).
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 20.0,
+        retry: RetryConfig | None = DEFAULT_RETRY,
+        headers: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._settings = _ClientSettings(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            retry=retry,
+            headers=headers,
+        )
+        self._http = httpx.Client(base_url=self._settings.base_url, transport=transport)
+        self.geo = GeoResource(self)
+        self.moon = MoonResource(self)
+        self.sky_events = SkyEventsResource(self)
+        self.western = WesternResource(self)
+        self._init_generated_resources(self)
+
+    def __enter__(self) -> FreeAstro:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        options: RequestOptions | None = None,
+    ) -> Any:
+        return self.request_raw(method, path, params=params, json=json, options=options).data
+
+    def request_raw(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        options: RequestOptions | None = None,
+    ) -> SDKResponse[Any]:
+        options = options or RequestOptions()
+        method = method.upper()
+        retry = self._settings.retry_config(method, options)
+        attempt = 0
+
+        while True:
+            try:
+                response = self._http.request(
+                    method,
+                    path,
+                    params=params,
+                    json=json,
+                    headers=self._settings.request_headers(options),
+                    timeout=options.timeout if options.timeout is not None else self._settings.timeout,
+                )
+            except httpx.TimeoutException as exc:
+                if retry and attempt < retry.retries:
+                    time.sleep(min(retry.base_delay * 2**attempt, retry.max_delay))
+                    attempt += 1
+                    continue
+                raise TimeoutError("FreeAstroAPI request timed out") from exc
+            except httpx.HTTPError as exc:
+                if retry and attempt < retry.retries:
+                    time.sleep(min(retry.base_delay * 2**attempt, retry.max_delay))
+                    attempt += 1
+                    continue
+                raise NetworkError("Unable to reach FreeAstroAPI") from exc
+
+            if response.is_success:
+                return SDKResponse(data=_response_data(response), response=response)
+            if retry and response.status_code in retry.statuses and attempt < retry.retries:
+                delay = _retry_after_seconds(response)
+                time.sleep(min(delay if delay is not None else retry.base_delay * 2**attempt, retry.max_delay))
+                attempt += 1
+                continue
+            raise error_from_response(response)
+
+
+class AsyncFreeAstro(AsyncGeneratedResources):
+    """Async FreeAstroAPI client with the same resources as :class:`FreeAstro`."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 20.0,
+        retry: RetryConfig | None = DEFAULT_RETRY,
+        headers: Mapping[str, str] | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._settings = _ClientSettings(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            retry=retry,
+            headers=headers,
+        )
+        self._http = httpx.AsyncClient(base_url=self._settings.base_url, transport=transport)
+        self.geo = AsyncGeoResource(self)
+        self.moon = AsyncMoonResource(self)
+        self.sky_events = AsyncSkyEventsResource(self)
+        self.western = AsyncWesternResource(self)
+        self._init_generated_resources(self)
+
+    async def __aenter__(self) -> AsyncFreeAstro:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        options: RequestOptions | None = None,
+    ) -> Any:
+        return (await self.request_raw(method, path, params=params, json=json, options=options)).data
+
+    async def request_raw(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        options: RequestOptions | None = None,
+    ) -> SDKResponse[Any]:
+        options = options or RequestOptions()
+        method = method.upper()
+        retry = self._settings.retry_config(method, options)
+        attempt = 0
+
+        while True:
+            try:
+                response = await self._http.request(
+                    method,
+                    path,
+                    params=params,
+                    json=json,
+                    headers=self._settings.request_headers(options),
+                    timeout=options.timeout if options.timeout is not None else self._settings.timeout,
+                )
+            except httpx.TimeoutException as exc:
+                if retry and attempt < retry.retries:
+                    await asyncio.sleep(min(retry.base_delay * 2**attempt, retry.max_delay))
+                    attempt += 1
+                    continue
+                raise TimeoutError("FreeAstroAPI request timed out") from exc
+            except httpx.HTTPError as exc:
+                if retry and attempt < retry.retries:
+                    await asyncio.sleep(min(retry.base_delay * 2**attempt, retry.max_delay))
+                    attempt += 1
+                    continue
+                raise NetworkError("Unable to reach FreeAstroAPI") from exc
+
+            if response.is_success:
+                return SDKResponse(data=_response_data(response), response=response)
+            if retry and response.status_code in retry.statuses and attempt < retry.retries:
+                delay = _retry_after_seconds(response)
+                await asyncio.sleep(min(delay if delay is not None else retry.base_delay * 2**attempt, retry.max_delay))
+                attempt += 1
+                continue
+            raise error_from_response(response)

freeastroapi/errors.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+import httpx
+
+
+class FreeAstroError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        request_id: str | None = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.details = details
+
+
+class AuthenticationError(FreeAstroError):
+    pass
+
+
+class PermissionError(FreeAstroError):
+    pass
+
+
+class ValidationError(FreeAstroError):
+    pass
+
+
+class ConflictError(FreeAstroError):
+    pass
+
+
+class RateLimitError(FreeAstroError):
+    def __init__(self, message: str, *, retry_after: float | None = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(FreeAstroError):
+    pass
+
+
+class NetworkError(FreeAstroError):
+    pass
+
+
+class TimeoutError(NetworkError):
+    pass
+
+
+def _retry_after_seconds(value: str | None) -> float | None:
+    if value is None:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        try:
+            retry_at = parsedate_to_datetime(value)
+            if retry_at.tzinfo is None:
+                retry_at = retry_at.replace(tzinfo=UTC)
+            return max(0.0, (retry_at - datetime.now(UTC)).total_seconds())
+        except (TypeError, ValueError, OverflowError):
+            return None
+
+
+def error_from_response(response: httpx.Response) -> FreeAstroError:
+    try:
+        payload: dict[str, Any] = response.json()
+    except (ValueError, TypeError):
+        payload = {}
+
+    detail = payload.get("detail")
+    message_value = (
+        detail
+        if isinstance(detail, str) and detail.strip()
+        else payload.get("message") or payload.get("error") or response.reason_phrase or f"HTTP {response.status_code}"
+    )
+    message = message_value if isinstance(message_value, str) else str(message_value)
+    code_value = payload.get("code")
+    code = code_value if isinstance(code_value, str) else None
+    request_id_value = response.headers.get("x-request-id") or payload.get("trace_id")
+    request_id = request_id_value if isinstance(request_id_value, str) else None
+
+    def error(error_type: type[FreeAstroError]) -> FreeAstroError:
+        return error_type(
+            message,
+            status=response.status_code,
+            code=code,
+            request_id=request_id,
+            details=payload,
+        )
+
+    if response.status_code == 401:
+        return error(AuthenticationError)
+    if response.status_code == 403:
+        return error(PermissionError)
+    if response.status_code in (400, 422):
+        return error(ValidationError)
+    if response.status_code == 409:
+        return error(ConflictError)
+    if response.status_code == 429:
+        retry_after = _retry_after_seconds(response.headers.get("retry-after"))
+        return RateLimitError(
+            message,
+            retry_after=retry_after,
+            status=response.status_code,
+            code=code,
+            request_id=request_id,
+            details=payload,
+        )
+    if response.status_code >= 500:
+        return error(ServerError)
+    return error(FreeAstroError)

freeastroapi/models.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class RequestModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class ResponseModel(BaseModel):
+    # Additive API response fields remain forward compatible and are preserved.
+    model_config = ConfigDict(extra="allow")
+
+
+class GeoSearchParams(RequestModel):
+    q: str = Field(min_length=2, max_length=100)
+    limit: int = Field(default=10, ge=1, le=50)
+    country: str | None = Field(default=None, pattern=r"^[A-Z]{2}$")
+
+
+class City(ResponseModel):
+    name: str
+    country: str
+    state: str | None = None
+    district: str | None = None
+    lat: float
+    lng: float
+    timezone: str
+    population: int
+
+
+class CitySearchResponse(ResponseModel):
+    results: list[City]
+    count: int
+
+
+class MoonLocationParams(RequestModel):
+    city: str | None = Field(default=None, min_length=1, max_length=200)
+    lat: float | None = Field(default=None, ge=-90, le=90)
+    lon: float | None = Field(default=None, ge=-180, le=180)
+    tz_str: str = "AUTO"
+    include_eclipse: bool = False
+    include_forecast: bool = False
+
+
+class MoonPhaseParams(MoonLocationParams):
+    date: str | None = None
+
+
+class MoonMonthParams(MoonLocationParams):
+    year: int = Field(ge=1, le=9999)
+    month: int = Field(ge=1, le=12)
+
+
+MoonPhaseName = Literal[
+    "New Moon",
+    "Waxing Crescent",
+    "First Quarter",
+    "Waxing Gibbous",
+    "Full Moon",
+    "Waning Gibbous",
+    "Last Quarter",
+    "Waning Crescent",
+]
+
+
+class MoonPhaseData(ResponseModel):
+    name: MoonPhaseName
+    phase_angle_deg: float
+    illumination: float
+    age_days: float
+    distance_km: float
+    is_waxing: bool
+
+
+class MaximumLocation(ResponseModel):
+    lat: float
+    lon: float
+
+
+class EclipseData(ResponseModel):
+    is_eclipse: bool
+    is_blood_moon: bool
+    kind: Literal["solar", "lunar"] | None = None
+    type: Literal["total", "annular", "hybrid", "partial", "penumbral"] | None = None
+    date: str | None = None
+    starts_at: str | None = None
+    ends_at: str | None = None
+    central_phase_starts_at: str | None = None
+    central_phase_ends_at: str | None = None
+    visibility: str | None = None
+    visible_at_location: bool | None = None
+    type_at_location: Literal["total", "annular", "partial"] | None = None
+    days_from_query: float | None = None
+    magnitude: float | None = None
+    obscuration: float | None = Field(default=None, ge=0, le=1)
+    maximum_location: MaximumLocation | None = None
+    local_starts_at: str | None = None
+    local_maximum_at: str | None = None
+    local_ends_at: str | None = None
+    magnitude_at_location: float | None = None
+    obscuration_at_location: float | None = Field(default=None, ge=0, le=1)
+
+
+class NextMoonPhases(ResponseModel):
+    new_moon: str
+    first_quarter: str
+    full_moon: str
+    last_quarter: str
+
+
+class MoonPhaseResponse(ResponseModel):
+    timestamp: str
+    phase: MoonPhaseData
+    eclipse: EclipseData | None = None
+    next_phases: NextMoonPhases
+
+
+class MoonMonthDay(MoonPhaseResponse):
+    calendar_date: str
+
+
+class MoonMonthResponse(ResponseModel):
+    year: int
+    month: int
+    month_name: str
+    days_in_month: int
+    calendar_basis: Literal["local", "utc"]
+    calendar_timezone: str
+    days: list[MoonMonthDay]
+
+
+class SkyEventsParams(RequestModel):
+    date: str
+    timezone: str = "UTC"
+    include_moon: bool = False
+    include_exact_hits: bool = True
+    include_moon_exact_hits: bool = False
+    include_ingresses: bool = True
+    include_retrogrades: bool = False
+    include_lunations: bool = False
+    include_formulation: bool = False
+
+
+class SkyEvent(ResponseModel):
+    id: str
+    type: Literal["moon_ingress", "planet_ingress", "exact_aspect", "retrograde_station", "lunation"]
+    title: str
+    formulation: str | None = None
+    exact_time: str
+    importance: Literal["daily", "medium", "major"]
+    body: str | None = None
+    sign: str | None = None
+    bodies: list[str] | None = None
+    aspect: Literal["conjunction", "sextile", "square", "trine", "opposition"] | None = None
+    angle: Literal[0, 60, 90, 120, 180] | None = None
+    orb: int | None = None
+    direction: Literal["retrograde", "direct"] | None = None
+    phase: Literal["new_moon", "full_moon"] | None = None
+
+
+class SkyEventsResponse(ResponseModel):
+    date: str
+    timezone: str
+    events: list[SkyEvent]
+
+
+class WesternSignRequest(RequestModel):
+    name: str = Field(default="Example User", max_length=200)
+    year: int = Field(ge=1, le=9999)
+    month: int = Field(ge=1, le=12)
+    day: int = Field(ge=1, le=31)
+    hour: int = Field(default=12, ge=0, le=23)
+    minute: int = Field(default=0, ge=0, le=59)
+    time_known: bool = True
+    city: str | None = Field(default=None, min_length=1, max_length=200)
+    lat: float | None = Field(default=None, ge=-90, le=90)
+    lng: float | None = Field(default=None, ge=-180, le=180)
+    tz_str: str = "AUTO"
+    house_system: Literal["placidus", "whole_sign", "equal", "regiomontanus", "koch", "porphyry"] = "placidus"
+    zodiac_type: Literal["tropical", "sidereal"] = "tropical"
+    sidereal_ayanamsa: Literal["lahiri", "raman", "kp", "fagan_bradley"] = "lahiri"
+
+    @model_validator(mode="after")
+    def require_location(self) -> WesternSignRequest:
+        if not self.city and (self.lat is None or self.lng is None):
+            raise ValueError("provide city or both lat and lng")
+        return self
+
+
+class WesternSignResponse(ResponseModel):
+    point: str
+    sign: str
+    sign_id: Literal[
+        "aries",
+        "taurus",
+        "gemini",
+        "cancer",
+        "leo",
+        "virgo",
+        "libra",
+        "scorpio",
+        "sagittarius",
+        "capricorn",
+        "aquarius",
+        "pisces",
+    ]
+    degree: float
+    abs_pos: float
+    house: int
+    interpretation: None = None
+
+
+class ErrorResponse(ResponseModel):
+    detail: Any | None = None
+    error: str | None = None
+    message: str | None = None
+    code: str | None = None
+    trace_id: str | None = None

freeastroapi/py.typed

@@ -0,0 +1 @@
+