kerykeion 5.0.0a11__py3-none-any.whl → 5.0.0b1__py3-none-any.whl

kerykeion/aspects/aspects_utils.py

@@ -5,15 +5,13 @@
 # TODO: Better documentation and unit tests
 
 from swisseph import difdeg2n
-from typing import Union, TYPE_CHECKING
-from kerykeion.kr_types.kr_models import AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel
-from kerykeion.kr_types.settings_models import KerykeionSettingsCelestialPointModel
+from typing import Union
+from kerykeion.schemas.kr_models import AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel
+from kerykeion.schemas.kr_literals import AspectMovementType
+from kerykeion.schemas.settings_models import KerykeionSettingsCelestialPointModel
 from kerykeion.settings.legacy.legacy_celestial_points_settings import DEFAULT_CELESTIAL_POINTS_SETTINGS
 
 
-if TYPE_CHECKING:
-    pass
-
 def get_aspect_from_two_points(
     aspects_settings: Union[list[dict], list[dict]],
     point_one: Union[float, int],
@@ -58,6 +56,77 @@ def get_aspect_from_two_points(
     }
 
 
+def calculate_aspect_movement(
+    point_one_abs_pos: float,
+    point_two_abs_pos: float,
+    aspect_degrees: int,
+    exact_orb_threshold: float = 0.05
+) -> AspectMovementType:
+    """
+    Calculate whether an aspect is applying, separating, or exact.
+
+    An aspect is:
+    - "Exact": When the orb is very tight (default < 0.17°)
+    - "Applying": When the faster planet is moving toward the exact aspect
+    - "Separating": When the faster planet is moving away from the exact aspect
+
+    For simplicity, we assume the first planet (p1) is faster than the second (p2).
+    This is generally true for:
+    - Moon vs outer planets
+    - Inner planets vs outer planets
+    - Transits (transiting planet vs natal planet)
+
+    Args:
+        point_one_abs_pos: Absolute position of first point (0-360°)
+        point_two_abs_pos: Absolute position of second point (0-360°)
+        aspect_degrees: The exact degree of the aspect (0, 60, 90, 120, 180, etc.)
+        exact_orb_threshold: Maximum orb to consider aspect "exact" (default 0.17°)
+
+    Returns:
+        "Applying", "Separating", or "Exact"
+
+    Example:
+        >>> # Moon at 45° applying to Sun at 50° (conjunction at 0°/360°)
+        >>> calculate_aspect_movement(45, 50, 0)
+        'Applying'
+        >>> # Moon at 55° separating from Sun at 50° (conjunction)
+        >>> calculate_aspect_movement(55, 50, 0)
+        'Separating'
+    """
+
+    # Calculate the angular distance
+    distance = abs(difdeg2n(point_one_abs_pos, point_two_abs_pos))
+    orbit = abs(distance - aspect_degrees)
+
+    # Check if aspect is exact (within tight orb)
+    if orbit <= exact_orb_threshold:
+        return "Exact"
+
+    # Calculate if p1 is ahead or behind p2 relative to the aspect
+    # We need to determine the direction of movement
+    diff = difdeg2n(point_one_abs_pos, point_two_abs_pos)
+
+    # For conjunction (0°) or opposition (180°)
+    if aspect_degrees == 0 or aspect_degrees == 360:
+        # If p1 is behind p2 (negative diff), it's applying
+        # If p1 is ahead of p2 (positive diff), it's separating
+        return "Applying" if diff < 0 else "Separating"
+
+    elif aspect_degrees == 180:
+        # For opposition, the logic is reversed
+        return "Applying" if abs(diff) < 180 else "Separating"
+
+    else:
+        # For other aspects (60°, 90°, 120°, 150°)
+        # Check if the distance is increasing or decreasing
+        # If distance < aspect_degrees and diff < 0: applying
+        # If distance > aspect_degrees or diff > 0: separating
+        if abs(diff) < aspect_degrees:
+            return "Applying" if diff < 0 else "Separating"
+        else:
+            return "Separating" if diff > 0 else "Applying"
+
+
 def planet_id_decoder(planets_settings: list[KerykeionSettingsCelestialPointModel], name: str) -> int:
     """
     Check if the name of the planet is the same in the settings and return