astrox-python 0.1.0__py3-none-any.whl

astrox/components/_constraints.py

@@ -0,0 +1,138 @@
+"""Constraint component value objects."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, TypeAlias
+
+from ._common import _include_if_supplied, _number_sequence_to_list
+
+@dataclass(frozen=True, kw_only=True)
+class ElevationConstraint:
+    """Elevation-angle constraint fragment shared by ASTROX entity and coverage inputs."""
+
+    minimum_deg: float | None = None
+    maximum_deg: float | None = None
+    maximum_enabled: bool | None = None
+    text: str | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Lower to an ASTROX elevation-angle constraint fragment."""
+        payload: dict[str, Any] = {"$type": "ElevationAngle"}
+        _include_if_supplied(payload, "MinimumValue", self.minimum_deg)
+        _include_if_supplied(payload, "MaximumValue", self.maximum_deg)
+        _include_if_supplied(payload, "IsMaximumEnabled", self.maximum_enabled)
+        _include_if_supplied(payload, "Text", self.text)
+        return payload
+
+
+@dataclass(frozen=True, kw_only=True)
+class RangeConstraint:
+    """Range constraint fragment shared by ASTROX entity and coverage inputs."""
+
+    minimum_km: float | None = None
+    maximum_km: float | None = None
+    maximum_enabled: bool | None = None
+    text: str | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Lower to an ASTROX range constraint fragment."""
+        payload: dict[str, Any] = {"$type": "Range"}
+        _include_if_supplied(payload, "MinimumValue", self.minimum_km)
+        _include_if_supplied(payload, "MaximumValue", self.maximum_km)
+        _include_if_supplied(payload, "IsMaximumEnabled", self.maximum_enabled)
+        _include_if_supplied(payload, "Text", self.text)
+        return payload
+
+
+@dataclass(frozen=True, kw_only=True)
+class AzElMaskConstraint:
+    """Azimuth/elevation mask constraint fragment shared by ASTROX entity and coverage inputs."""
+
+    az_el_mask_rad: tuple[float, ...]
+    max_range_km: float | None = None
+    text: str | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Lower to an ASTROX azimuth/elevation mask constraint fragment."""
+        payload: dict[str, Any] = {
+            "$type": "AzElMask",
+            "AzElMaskData": list(self.az_el_mask_rad),
+        }
+        _include_if_supplied(payload, "MaxRange", self.max_range_km)
+        _include_if_supplied(payload, "Text", self.text)
+        return payload
+
+
+Constraint: TypeAlias = ElevationConstraint | RangeConstraint | AzElMaskConstraint
+
+
+_CONSTRAINT_TYPES = (ElevationConstraint, RangeConstraint, AzElMaskConstraint)
+
+
+def elevation_constraint(
+    *,
+    minimum_deg: float | None = None,
+    maximum_deg: float | None = None,
+    maximum_enabled: bool | None = None,
+    text: str | None = None,
+) -> ElevationConstraint:
+    """Create an elevation-angle constraint fragment."""
+    return ElevationConstraint(
+        minimum_deg=minimum_deg,
+        maximum_deg=maximum_deg,
+        maximum_enabled=maximum_enabled,
+        text=text,
+    )
+
+
+def range_constraint(
+    *,
+    minimum_km: float | None = None,
+    maximum_km: float | None = None,
+    maximum_enabled: bool | None = None,
+    text: str | None = None,
+) -> RangeConstraint:
+    """Create a range constraint fragment."""
+    return RangeConstraint(
+        minimum_km=minimum_km,
+        maximum_km=maximum_km,
+        maximum_enabled=maximum_enabled,
+        text=text,
+    )
+
+
+def az_el_mask_constraint(
+    *,
+    az_el_mask_rad: Sequence[float],
+    max_range_km: float | None = None,
+    text: str | None = None,
+) -> AzElMaskConstraint:
+    """Create an azimuth/elevation mask constraint fragment.
+
+    ``az_el_mask_rad`` is a flat sequence of alternating azimuth and elevation
+    samples in radians. ASTROX interpolates the mask piecewise-linearly in
+    azimuth and applies it at the constrained participant. Live validation shows
+    this constraint is only meaningful for ``SitePosition`` participants; the
+    server rejects it for moving position sources.
+
+    ``max_range_km`` is forwarded but is not enforced by ASTROX. The live
+    OpenAPI description and server behavior both treat it as documentation-only.
+    """
+    return AzElMaskConstraint(
+        az_el_mask_rad=tuple(
+            _number_sequence_to_list(
+                az_el_mask_rad,
+                parameter="az_el_mask_rad",
+            )
+        ),
+        max_range_km=max_range_km,
+        text=text,
+    )
+
+
+def _constraint_to_wire(constraint: Constraint) -> dict[str, Any]:
+    if not isinstance(constraint, _CONSTRAINT_TYPES):
+        raise TypeError("constraint must be an astrox.components constraint value")
+    return constraint.to_wire()

astrox/components/_objects.py

@@ -0,0 +1,167 @@
+"""Named ASTROX analysis object components."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from ._axes import EntityAxes, _AXES_TYPES, _axes_to_wire
+from ._common import (
+    _include_if_supplied,
+    _typed_tuple,
+    _validate_group_restriction,
+)
+from ._constraints import Constraint, _CONSTRAINT_TYPES, _constraint_to_wire
+from ._positions import EntityPosition, _POSITION_TYPES, _position_to_wire
+from ._sensors import (
+    EntitySensor,
+    SensorPointing,
+    _SENSOR_POINTING_TYPES,
+    _SENSOR_TYPES,
+    _sensor_pointing_to_wire,
+    _sensor_to_wire,
+)
+from ._vgt import VgtProvider, _vgt_to_wire
+
+def _entities_to_tuple(
+    values: Sequence[Entity],
+    *,
+    parameter: str,
+) -> tuple[Entity, ...]:
+    if isinstance(values, (str, bytes)) or not isinstance(values, Sequence):
+        raise TypeError(f"{parameter} must be a sequence of Entity values")
+    items = tuple(values)
+    if not all(isinstance(item, Entity) for item in items):
+        raise TypeError(f"{parameter} must be a sequence of Entity values")
+    return items
+
+
+@dataclass(frozen=True, kw_only=True)
+class Entity:
+    """Named ASTROX analysis object composed from a position source and metadata."""
+
+    name: str
+    position: EntityPosition
+    description: str | None = None
+    vgt: VgtProvider | None = None
+    orientation: EntityAxes | None = None
+    sensor: EntitySensor | None = None
+    sensor_pointing: SensorPointing | None = None
+    constraints: tuple[Constraint, ...] | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Lower to the common ASTROX entity body."""
+        payload: dict[str, Any] = {
+            "Name": self.name,
+        }
+        _include_if_supplied(payload, "Description", self.description)
+        if self.vgt is not None:
+            payload["Vgt"] = _vgt_to_wire(self.vgt)
+        payload["Position"] = _position_to_wire(self.position)
+        if self.orientation is not None:
+            payload["Orientation"] = _axes_to_wire(self.orientation)
+        if self.sensor is not None:
+            payload["Sensor"] = _sensor_to_wire(self.sensor)
+        if self.sensor_pointing is not None:
+            payload["SensorPointing"] = _sensor_pointing_to_wire(self.sensor_pointing)
+        if self.constraints is not None:
+            payload["Constraints"] = [
+                _constraint_to_wire(constraint) for constraint in self.constraints
+            ]
+        return payload
+
+
+@dataclass(frozen=True, kw_only=True)
+class EntityGroup:
+    """Named entity group for workflows that accept grouped entities."""
+
+    name: str
+    members: tuple[Entity, ...]
+    from_restriction: str | None = None
+    from_number: int | None = None
+    to_restriction: str | None = None
+    to_number: int | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Lower to the ASTROX EntityPathGroup fragment."""
+        payload: dict[str, Any] = {
+            "$type": "EntityPathGroup",
+            "Name": self.name,
+            "AssignedObjects": [member.to_wire() for member in self.members],
+        }
+        _include_if_supplied(payload, "FromAccess_Restriction", self.from_restriction)
+        _include_if_supplied(payload, "FromAccess_Number", self.from_number)
+        _include_if_supplied(payload, "ToAccess_Restriction", self.to_restriction)
+        _include_if_supplied(payload, "ToAccess_Number", self.to_number)
+        return payload
+
+
+def entity(
+    *,
+    name: str,
+    position: EntityPosition,
+    description: str | None = None,
+    vgt: VgtProvider | None = None,
+    orientation: EntityAxes | None = None,
+    sensor: EntitySensor | None = None,
+    sensor_pointing: SensorPointing | None = None,
+    constraints: Sequence[Constraint] | None = None,
+) -> Entity:
+    """Create a named ASTROX analysis object."""
+    if not isinstance(position, _POSITION_TYPES):
+        raise TypeError("position must be an astrox.components position value")
+    if vgt is not None and not isinstance(vgt, VgtProvider):
+        raise TypeError("vgt must be an astrox.components.VgtProvider value")
+    if orientation is not None and not isinstance(orientation, _AXES_TYPES):
+        raise TypeError("orientation must be an astrox.components axes value")
+    if sensor is not None and not isinstance(sensor, _SENSOR_TYPES):
+        raise TypeError("sensor must be an astrox.components sensor value")
+    if sensor_pointing is not None and not isinstance(
+        sensor_pointing,
+        _SENSOR_POINTING_TYPES,
+    ):
+        raise TypeError(
+            "sensor_pointing must be an astrox.components sensor-pointing value"
+        )
+    constraint_items = (
+        _typed_tuple(constraints, _CONSTRAINT_TYPES, parameter="constraints")
+        if constraints is not None
+        else None
+    )
+    return Entity(
+        name=name,
+        position=position,
+        description=description,
+        vgt=vgt,
+        orientation=orientation,
+        sensor=sensor,
+        sensor_pointing=sensor_pointing,
+        constraints=constraint_items,
+    )
+
+
+def entity_group(
+    *,
+    name: str,
+    members: Sequence[Entity],
+    from_restriction: str | None = None,
+    from_number: int | None = None,
+    to_restriction: str | None = None,
+    to_number: int | None = None,
+) -> EntityGroup:
+    """Create a named entity group."""
+    return EntityGroup(
+        name=name,
+        members=_entities_to_tuple(members, parameter="members"),
+        from_restriction=_validate_group_restriction(
+            from_restriction,
+            parameter="from_restriction",
+        ),
+        from_number=from_number,
+        to_restriction=_validate_group_restriction(
+            to_restriction,
+            parameter="to_restriction",
+        ),
+        to_number=to_number,
+    )