astrox-python 0.1.0__py3-none-any.whl

astrox/coverage/simple_coverage.py

@@ -0,0 +1,152 @@
+"""Simple-coverage FOM routes."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from astrox import components
+
+from ._core import CoverageGrid
+from ._fom import post_coverage_input, post_time_value_by_grid_point_input
+
+__all__ = [
+    "by_grid_point",
+    "by_grid_point_at_time",
+    "grid_stats",
+    "grid_stats_over_time",
+]
+
+
+def by_grid_point(
+    *,
+    start: str,
+    stop: str,
+    grid: CoverageGrid,
+    assets: Sequence[components.Entity],
+    minimum_assets: int | None = None,
+    exactly_assets: int | None = None,
+    grid_point_sensor: components.EntitySensor | None = None,
+    grid_point_constraints: Sequence[components.Constraint] | None = None,
+    include_asset_access_results: bool | None = None,
+    include_coverage_points: bool | None = None,
+    step_s: float | None = None,
+    description: str | None = None,
+) -> dict[str, Any]:
+    """Compute simple-coverage FOM values for each grid point."""
+    return post_coverage_input(
+        "/Coverage/FOM/ValueByGridPoint/SimpleCoverage",
+        start=start,
+        stop=stop,
+        grid=grid,
+        assets=assets,
+        minimum_assets=minimum_assets,
+        exactly_assets=exactly_assets,
+        grid_point_sensor=grid_point_sensor,
+        grid_point_constraints=grid_point_constraints,
+        include_asset_access_results=include_asset_access_results,
+        include_coverage_points=include_coverage_points,
+        step_s=step_s,
+        description=description,
+    )
+
+
+def by_grid_point_at_time(
+    *,
+    time: str,
+    start: str,
+    stop: str,
+    grid: CoverageGrid,
+    assets: Sequence[components.Entity],
+    minimum_assets: int | None = None,
+    exactly_assets: int | None = None,
+    grid_point_sensor: components.EntitySensor | None = None,
+    grid_point_constraints: Sequence[components.Constraint] | None = None,
+    include_asset_access_results: bool | None = None,
+    include_coverage_points: bool | None = None,
+    step_s: float | None = None,
+    description: str | None = None,
+) -> dict[str, Any]:
+    """Compute simple-coverage FOM values for each grid point at one time."""
+    return post_time_value_by_grid_point_input(
+        "/Coverage/FOM/ValueByGridPointAtTime/SimpleCoverage",
+        time=time,
+        start=start,
+        stop=stop,
+        grid=grid,
+        assets=assets,
+        minimum_assets=minimum_assets,
+        exactly_assets=exactly_assets,
+        grid_point_sensor=grid_point_sensor,
+        grid_point_constraints=grid_point_constraints,
+        include_asset_access_results=include_asset_access_results,
+        include_coverage_points=include_coverage_points,
+        step_s=step_s,
+        description=description,
+    )
+
+
+def grid_stats(
+    *,
+    start: str,
+    stop: str,
+    grid: CoverageGrid,
+    assets: Sequence[components.Entity],
+    minimum_assets: int | None = None,
+    exactly_assets: int | None = None,
+    grid_point_sensor: components.EntitySensor | None = None,
+    grid_point_constraints: Sequence[components.Constraint] | None = None,
+    include_asset_access_results: bool | None = None,
+    include_coverage_points: bool | None = None,
+    step_s: float | None = None,
+    description: str | None = None,
+) -> dict[str, Any]:
+    """Compute minimum, maximum, and average simple-coverage FOM values."""
+    return post_coverage_input(
+        "/Coverage/FOM/GridStats/SimpleCoverage",
+        start=start,
+        stop=stop,
+        grid=grid,
+        assets=assets,
+        minimum_assets=minimum_assets,
+        exactly_assets=exactly_assets,
+        grid_point_sensor=grid_point_sensor,
+        grid_point_constraints=grid_point_constraints,
+        include_asset_access_results=include_asset_access_results,
+        include_coverage_points=include_coverage_points,
+        step_s=step_s,
+        description=description,
+    )
+
+
+def grid_stats_over_time(
+    *,
+    start: str,
+    stop: str,
+    grid: CoverageGrid,
+    assets: Sequence[components.Entity],
+    minimum_assets: int | None = None,
+    exactly_assets: int | None = None,
+    grid_point_sensor: components.EntitySensor | None = None,
+    grid_point_constraints: Sequence[components.Constraint] | None = None,
+    include_asset_access_results: bool | None = None,
+    include_coverage_points: bool | None = None,
+    step_s: float | None = None,
+    description: str | None = None,
+) -> dict[str, Any]:
+    """Compute simple-coverage grid statistics over time."""
+    return post_coverage_input(
+        "/Coverage/FOM/GridStatsOverTime/SimpleCoverage",
+        start=start,
+        stop=stop,
+        grid=grid,
+        assets=assets,
+        minimum_assets=minimum_assets,
+        exactly_assets=exactly_assets,
+        grid_point_sensor=grid_point_sensor,
+        grid_point_constraints=grid_point_constraints,
+        include_asset_access_results=include_asset_access_results,
+        include_coverage_points=include_coverage_points,
+        step_s=step_s,
+        description=description,
+    )

astrox/exceptions.py

@@ -0,0 +1,92 @@
+"""Custom exceptions for the astrox package."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AstroxError(Exception):
+    """Base exception for all astrox errors."""
+
+    pass
+
+
+class AstroxAPIError(AstroxError):
+    """API returned IsSuccess=false or other API-level error."""
+
+    def __init__(self, message: str, endpoint: str, response: Any):
+        """Initialize API error.
+
+        Args:
+            message: Error message from API
+            endpoint: API endpoint that was called
+            response: Response object from requests
+        """
+        self.message = message
+        self.endpoint = endpoint
+        self.response = response
+        super().__init__(message)
+
+
+class AstroxHTTPError(AstroxError):
+    """HTTP status code indicates error."""
+
+    def __init__(self, status_code: int, message: str, endpoint: str, response: Any):
+        """Initialize HTTP error.
+
+        Args:
+            status_code: HTTP status code
+            message: Error message
+            endpoint: API endpoint that was called
+            response: Response object from requests
+        """
+        self.status_code = status_code
+        self.message = message
+        self.endpoint = endpoint
+        self.response = response
+        super().__init__(f"HTTP {status_code}: {message}")
+
+
+class AstroxTimeoutError(AstroxError):
+    """Request timed out."""
+
+    def __init__(self, endpoint: str, timeout: float):
+        """Initialize timeout error.
+
+        Args:
+            endpoint: API endpoint that was called
+            timeout: Timeout value in seconds
+        """
+        self.endpoint = endpoint
+        self.timeout = timeout
+        super().__init__(f"Request to {endpoint} timed out after {timeout}s")
+
+
+class AstroxConnectionError(AstroxError):
+    """Failed to connect to API."""
+
+    def __init__(self, message: str, original_error: Exception | None):
+        """Initialize connection error.
+
+        Args:
+            message: Error message
+            original_error: Original exception that caused the error
+        """
+        self.message = message
+        self.original_error = original_error
+        super().__init__(message)
+
+
+class AstroxValidationError(AstroxError):
+    """Response validation failed."""
+
+    def __init__(self, message: str, errors: list[dict[str, Any]]):
+        """Initialize validation error.
+
+        Args:
+            message: Error message
+            errors: List of validation errors from the response model
+        """
+        self.message = message
+        self.errors = errors
+        super().__init__(message)

astrox/lighting.py

@@ -0,0 +1,121 @@
+"""Lighting analysis functions."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from numbers import Real
+from typing import Any
+
+from astrox import components
+from astrox._http import raw
+
+__all__ = [
+    "lighting_times",
+    "solar_aer",
+    "solar_intensity",
+]
+
+
+def _include_if_supplied(payload: dict[str, Any], wire_key: str, value: Any) -> None:
+    if value is not None:
+        payload[wire_key] = value
+
+
+def _number_sequence_to_list(value: Sequence[float], *, parameter: str) -> list[float]:
+    if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
+        raise TypeError(f"{parameter} must be a sequence of numbers")
+    items = list(value)
+    if not all(isinstance(item, Real) and not isinstance(item, bool) for item in items):
+        raise TypeError(f"{parameter} must be a sequence of numbers")
+    return items
+
+
+def _string_sequence_to_list(value: Sequence[str], *, parameter: str) -> list[str]:
+    if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
+        raise TypeError(f"{parameter} must be a sequence of strings")
+    items = list(value)
+    if not all(isinstance(item, str) for item in items):
+        raise TypeError(f"{parameter} must be a sequence of strings")
+    return items
+
+
+def lighting_times(
+    *,
+    start: str,
+    stop: str,
+    position: components.EntityPosition,
+    description: str | None = None,
+    az_el_mask_data: Sequence[float] | None = None,
+    occultation_bodies: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Compute sunlight, penumbra, and umbra intervals for a position source."""
+    payload: dict[str, Any] = {
+        "Start": start,
+        "Stop": stop,
+        "Position": components._position_to_wire(position),
+    }
+    _include_if_supplied(payload, "Description", description)
+    if az_el_mask_data is not None:
+        payload["AzElMaskData"] = _number_sequence_to_list(
+            az_el_mask_data,
+            parameter="az_el_mask_data",
+        )
+    if occultation_bodies is not None:
+        payload["OccultationBodies"] = _string_sequence_to_list(
+            occultation_bodies,
+            parameter="occultation_bodies",
+        )
+
+    return raw.post("/Lighting/LightingTimes", json=payload)
+
+
+def solar_intensity(
+    *,
+    start: str,
+    stop: str,
+    position: components.EntityPosition,
+    description: str | None = None,
+    az_el_mask_data: Sequence[float] | None = None,
+    step_s: float | None = None,
+    occultation_bodies: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Compute solar intensity samples for a position source."""
+    payload: dict[str, Any] = {
+        "Start": start,
+        "Stop": stop,
+        "Position": components._position_to_wire(position),
+    }
+    _include_if_supplied(payload, "Description", description)
+    _include_if_supplied(payload, "TimeStepSec", step_s)
+    if az_el_mask_data is not None:
+        payload["AzElMaskData"] = _number_sequence_to_list(
+            az_el_mask_data,
+            parameter="az_el_mask_data",
+        )
+    if occultation_bodies is not None:
+        payload["OccultationBodies"] = _string_sequence_to_list(
+            occultation_bodies,
+            parameter="occultation_bodies",
+        )
+
+    return raw.post("/Lighting/SolarIntensity", json=payload)
+
+
+def solar_aer(
+    *,
+    start: str,
+    stop: str,
+    position: components.EntityPosition,
+    text: str | None = None,
+    step_s: int | None = None,
+) -> dict[str, Any]:
+    """Compute solar azimuth, elevation, and range samples for a position source."""
+    payload: dict[str, Any] = {
+        "Start": start,
+        "Stop": stop,
+        "Position": components._position_to_wire(position),
+    }
+    _include_if_supplied(payload, "Text", text)
+    _include_if_supplied(payload, "TimeStepSec", step_s)
+
+    return raw.post("/Lighting/SolarAER", json=payload)