kerykeion 4.26.3__py3-none-any.whl → 5.0.0__py3-none-any.whl

kerykeion/utilities.py

@@ -1,16 +1,39 @@
-from kerykeion.kr_types import KerykeionPointModel, KerykeionException, ZodiacSignModel, AstrologicalSubjectModel, LunarPhaseModel
-from kerykeion.kr_types.kr_literals import LunarPhaseEmoji, LunarPhaseName, PointType, Planet, Houses, AxialCusps
-from typing import Union, get_args, TYPE_CHECKING
+"""
+Author: Giacomo Battaglia
+Copyright: (C) 2025 Kerykeion Project
+License: AGPL-3.0
+"""
+
+from kerykeion.schemas import (
+    KerykeionPointModel,
+    KerykeionException,
+    ZodiacSignModel,
+    AstrologicalSubjectModel,
+    LunarPhaseModel,
+    CompositeSubjectModel,
+    PlanetReturnModel,
+)
+from kerykeion.schemas.kr_literals import LunarPhaseEmoji, LunarPhaseName, PointType, AstrologicalPoint, Houses
+from typing import Union, Optional, get_args
 import logging
 import math
 import re
+from datetime import datetime
 
-if TYPE_CHECKING:
-    from kerykeion import AstrologicalSubject
 
+def get_number_from_name(name: AstrologicalPoint) -> int:
+    """
+    Convert an astrological point name to its corresponding numerical identifier.
 
-def get_number_from_name(name: Planet) -> int:
-    """Utility function, gets planet id from the name."""
+    Args:
+        name: The name of the astrological point
+
+    Returns:
+        The numerical identifier used in Swiss Ephemeris calculations
+
+    Raises:
+        KerykeionException: If the name is not recognized
+    """
 
     if name == "Sun":
         return 0
@@ -32,50 +55,55 @@ def get_number_from_name(name: Planet) -> int:
         return 8
     elif name == "Pluto":
         return 9
-    elif name == "Mean_Node":
+    elif name == "Mean_North_Lunar_Node":
         return 10
-    elif name == "True_Node":
+    elif name == "True_North_Lunar_Node":
         return 11
     # Note: Swiss ephemeris library has no constants for south nodes. We're using integers >= 1000 for them.
-    elif name == "Mean_South_Node":
+    elif name == "Mean_South_Lunar_Node":
         return 1000
-    elif name == "True_South_Node":
+    elif name == "True_South_Lunar_Node":
         return 1100
     elif name == "Chiron":
         return 15
     elif name == "Mean_Lilith":
         return 12
-    elif name == "Ascendant": # TODO: Is this needed?
+    elif name == "Ascendant":  # TODO: Is this needed?
         return 9900
-    elif name == "Descendant": # TODO: Is this needed?
+    elif name == "Descendant":  # TODO: Is this needed?
         return 9901
-    elif name == "Medium_Coeli": # TODO: Is this needed?
+    elif name == "Medium_Coeli":  # TODO: Is this needed?
         return 9902
-    elif name == "Imum_Coeli": # TODO: Is this needed?
+    elif name == "Imum_Coeli":  # TODO: Is this needed?
         return 9903
     else:
         raise KerykeionException(f"Error in getting number from name! Name: {name}")
 
 
 def get_kerykeion_point_from_degree(
-    degree: Union[int, float], name: Union[Planet, Houses, AxialCusps], point_type: PointType
+    degree: Union[int, float], name: Union[AstrologicalPoint, Houses], point_type: PointType, speed: Optional[float] = None, declination: Optional[float] = None
 ) -> KerykeionPointModel:
     """
-    Returns a KerykeionPointModel object based on the given degree.
+    Create a KerykeionPointModel from a degree position.
 
     Args:
-        degree (Union[int, float]): The degree of the celestial point.
-        name (str): The name of the celestial point.
-        point_type (PointType): The type of the celestial point.
-
-    Raises:
-        KerykeionException: If the degree is not within the valid range (0-360).
+        degree: The degree position (0-360, negative values are converted to positive)
+        name: The name of the celestial point or house
+        point_type: The type classification of the point
+        speed: The velocity/speed of the celestial point in degrees per day (optional)
+        declination: The declination of the celestial point in degrees (optional)
 
     Returns:
-        KerykeionPointModel: The model representing the celestial point.
+        A KerykeionPointModel with calculated zodiac sign, position, and properties
+
+    Raises:
+        KerykeionException: If the degree is >= 360 after normalization
     """
+    # If - single degree is given, convert it to a positive degree
+    if degree < 0:
+        degree = degree % 360
 
-    if degree < 0 or degree >= 360:
+    if degree >= 360:
         raise KerykeionException(f"Error in calculating positions! Degrees: {degree}")
 
     ZODIAC_SIGNS = {
@@ -107,14 +135,17 @@ def get_kerykeion_point_from_degree(
         abs_pos=degree,
         emoji=zodiac_sign.emoji,
         point_type=point_type,
+        speed=speed,
+        declination=declination,
     )
 
+
 def setup_logging(level: str) -> None:
     """
-    Setup logging for testing.
+    Configure logging for the application.
 
     Args:
-        level: Log level as a string, options: debug, info, warning, error
+        level: Log level as string (debug, info, warning, error, critical)
     """
     logging_options: dict[str, int] = {
         "debug": logging.DEBUG,
@@ -129,23 +160,26 @@ def setup_logging(level: str) -> None:
 
 
 def is_point_between(
-    start_point: Union[int, float],
-    end_point: Union[int, float],
-    evaluated_point: Union[int, float]
+    start_point: Union[int, float], end_point: Union[int, float], evaluated_point: Union[int, float]
 ) -> bool:
     """
-    Determines if a point is between two others on a circle, with additional rules:
-    - If evaluated_point == start_point, it is considered between.
-    - If evaluated_point == end_point, it is NOT considered between.
-    - The range between start_point and end_point must not exceed 180°.
+    Determine if a point lies between two other points on a circle.
+
+    Special rules:
+    - If evaluated_point equals start_point, returns True
+    - If evaluated_point equals end_point, returns False
+    - The arc between start_point and end_point must not exceed 180°
 
     Args:
-        - start_point: The first point on the circle.
-        - end_point: The second point on the circle.
-        - evaluated_point: The point to check.
+        start_point: The starting point on the circle
+        end_point: The ending point on the circle
+        evaluated_point: The point to evaluate
 
     Returns:
-        - True if evaluated_point is between start_point and end_point, False otherwise.
+        True if evaluated_point is between start_point and end_point, False otherwise
+
+    Raises:
+        KerykeionException: If the angular difference exceeds 180°
     """
 
     # Normalize angles to [0, 360)
@@ -159,7 +193,9 @@ def is_point_between(
     # Ensure the range is not greater than 180°. Otherwise, it is not truly defined what
     # being located in between two points on a circle actually means.
     if angular_difference > 180:
-        raise KerykeionException(f"The angle between start and end point is not allowed to exceed 180°, yet is: {angular_difference}")
+        raise KerykeionException(
+            f"The angle between start and end point is not allowed to exceed 180°, yet is: {angular_difference}"
+        )
 
     # Handle explicitly when evaluated_point == start_point. Note: It may happen for mathematical
     # reasons that evaluated_point and start_point deviate very slightly from each other, but
@@ -178,20 +214,19 @@ def is_point_between(
     return (0 <= p1_p3) and (p1_p3 < angular_difference)
 
 
-
 def get_planet_house(planet_position_degree: Union[int, float], houses_degree_ut_list: list) -> Houses:
     """
-    Determines the house in which a planet is located based on its position in degrees.
+    Determine which house contains a planet based on its degree position.
 
     Args:
-        planet_position_degree (Union[int, float]): The position of the planet in degrees.
-        houses_degree_ut_list (list): A list of the houses in degrees (0-360).
+        planet_position_degree: The planet's position in degrees (0-360)
+        houses_degree_ut_list: List of house cusp degrees
 
     Returns:
-        str: The house in which the planet is located.
+        The house name containing the planet
 
     Raises:
-        ValueError: If the planet's position does not fall within any house range.
+        ValueError: If the planet's position doesn't fall within any house range
     """
 
     house_names = get_args(Houses)
@@ -210,13 +245,16 @@ def get_planet_house(planet_position_degree: Union[int, float], houses_degree_ut
 
 def get_moon_emoji_from_phase_int(phase: int) -> LunarPhaseEmoji:
     """
-    Returns the emoji of the moon phase.
+    Get the emoji representation of a lunar phase.
 
     Args:
-        - phase: The phase of the moon (0-28)
+        phase: The lunar phase number (0-28)
 
     Returns:
-        - The emoji of the moon phase
+        The corresponding emoji for the lunar phase
+
+    Raises:
+        KerykeionException: If phase is outside valid range
     """
 
     lunar_phase_emojis = get_args(LunarPhaseEmoji)
@@ -243,23 +281,26 @@ def get_moon_emoji_from_phase_int(phase: int) -> LunarPhaseEmoji:
 
     return result
 
+
 def get_moon_phase_name_from_phase_int(phase: int) -> LunarPhaseName:
     """
-    Returns the name of the moon phase.
+    Get the name of a lunar phase from its numerical value.
 
     Args:
-        - phase: The phase of the moon (0-28)
+        phase: The lunar phase number (0-28)
 
     Returns:
-        - The name of the moon phase
+        The corresponding name for the lunar phase
+
+    Raises:
+        KerykeionException: If phase is outside valid range
     """
     lunar_phase_names = get_args(LunarPhaseName)
 
-
     if phase == 1:
         result = lunar_phase_names[0]
     elif phase < 7:
-        result =  lunar_phase_names[1]
+        result = lunar_phase_names[1]
     elif 7 <= phase <= 9:
         result = lunar_phase_names[2]
     elif phase < 14:
@@ -281,8 +322,15 @@ def get_moon_phase_name_from_phase_int(phase: int) -> LunarPhaseName:
 
 def check_and_adjust_polar_latitude(latitude: float) -> float:
     """
-        Utility function to check if the location is in the polar circle.
-        If it is, it sets the latitude to 66 or -66 degrees.
+    Adjust latitude values for polar regions to prevent calculation errors.
+
+    Latitudes beyond ±66° are clamped to ±66° for house calculations.
+
+    Args:
+        latitude: The original latitude value
+
+    Returns:
+        The adjusted latitude value, clamped between -66° and 66°
     """
     if latitude > 66.0:
         latitude = 66.0
@@ -295,45 +343,57 @@ def check_and_adjust_polar_latitude(latitude: float) -> float:
     return latitude
 
 
-def get_houses_list(subject: Union["AstrologicalSubject", AstrologicalSubjectModel]) -> list[KerykeionPointModel]:
+def get_houses_list(
+    subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel]
+) -> list[KerykeionPointModel]:
     """
-    Return the names of the houses in the order of the houses.
+    Get a list of house objects in order from the subject.
+
+    Args:
+        subject: The astrological subject containing house data
+
+    Returns:
+        List of KerykeionPointModel objects representing the houses
     """
     houses_absolute_position_list = []
     for house in subject.houses_names_list:
-            houses_absolute_position_list.append(subject[house.lower()])
+        houses_absolute_position_list.append(subject[house.lower()])
 
     return houses_absolute_position_list
 
 
-def get_available_astrological_points_list(subject: Union["AstrologicalSubject", AstrologicalSubjectModel]) -> list[KerykeionPointModel]:
+def get_available_astrological_points_list(
+    subject: AstrologicalSubjectModel
+) -> list[KerykeionPointModel]:
     """
-    Return the names of the planets in the order of the planets.
-    The names can be used to access the planets from the AstrologicalSubject object with the __getitem__ method or the [] operator.
+    Get a list of active astrological point objects from the subject.
+
+    Args:
+        subject: The astrological subject containing point data
+
+    Returns:
+        List of KerykeionPointModel objects for all active points
     """
     planets_absolute_position_list = []
-    for planet in subject.planets_names_list:
-            planets_absolute_position_list.append(subject[planet.lower()])
-
-    for axis in subject.axial_cusps_names_list:
-        planets_absolute_position_list.append(subject[axis.lower()])
+    for planet in subject.active_points:
+        planets_absolute_position_list.append(subject[planet.lower()])
 
     return planets_absolute_position_list
 
 
 def circular_mean(first_position: Union[int, float], second_position: Union[int, float]) -> float:
     """
-    Computes the circular mean of two astrological positions (e.g., house cusps, planets).
+    Calculate the circular mean of two angular positions.
 
-    This function ensures that positions crossing 0° Aries (360°) are correctly averaged,
-    avoiding errors that occur with simple linear means.
+    This method correctly handles positions that cross the 0°/360° boundary,
+    avoiding errors that occur with simple arithmetic means.
 
     Args:
-        position1 (Union[int, float]): First position in degrees (0-360).
-        position2 (Union[int, float]): Second position in degrees (0-360).
+        first_position: First angular position in degrees (0-360)
+        second_position: Second angular position in degrees (0-360)
 
     Returns:
-        float: The circular mean position in degrees (0-360).
+        The circular mean position in degrees (0-360)
     """
     x = (math.cos(math.radians(first_position)) + math.cos(math.radians(second_position))) / 2
     y = (math.sin(math.radians(first_position)) + math.sin(math.radians(second_position))) / 2
@@ -348,18 +408,15 @@ def circular_mean(first_position: Union[int, float], second_position: Union[int,
 
 def calculate_moon_phase(moon_abs_pos: float, sun_abs_pos: float) -> LunarPhaseModel:
     """
-    Calculate the lunar phase based on the positions of the moon and sun.
+    Calculate lunar phase information from Sun and Moon positions.
 
     Args:
-    - moon_abs_pos (float): The absolute position of the moon.
-    - sun_abs_pos (float): The absolute position of the sun.
+        moon_abs_pos: Absolute position of the Moon in degrees
+        sun_abs_pos: Absolute position of the Sun in degrees
 
     Returns:
-    - dict: A dictionary containing the lunar phase information.
+        LunarPhaseModel containing phase data, emoji, and name
     """
-    # Initialize moon_phase and sun_phase to None in case of an error
-    moon_phase, sun_phase = None, None
-
     # Calculate the anti-clockwise degrees between the sun and moon
     degrees_between = (moon_abs_pos - sun_abs_pos) % 360
 
@@ -367,42 +424,23 @@ def calculate_moon_phase(moon_abs_pos: float, sun_abs_pos: float) -> LunarPhaseM
     step = 360.0 / 28.0
     moon_phase = int(degrees_between // step) + 1
 
-    # Define the sun phase steps
-    sunstep = [
-        0, 30, 40, 50, 60, 70, 80, 90, 120, 130, 140, 150, 160, 170, 180,
-        210, 220, 230, 240, 250, 260, 270, 300, 310, 320, 330, 340, 350
-    ]
-
-    # Calculate the sun phase (1-28) based on the degrees between the sun and moon
-    for x in range(len(sunstep)):
-        low = sunstep[x]
-        high = sunstep[x + 1] if x < len(sunstep) - 1 else 360
-        if low <= degrees_between < high:
-            sun_phase = x + 1
-            break
-
-    # Create a dictionary with the lunar phase information
-    lunar_phase_dictionary = {
-        "degrees_between_s_m": degrees_between,
-        "moon_phase": moon_phase,
-        "sun_phase": sun_phase,
-        "moon_emoji": get_moon_emoji_from_phase_int(moon_phase),
-        "moon_phase_name": get_moon_phase_name_from_phase_int(moon_phase)
-    }
-
-    return LunarPhaseModel(**lunar_phase_dictionary)
+    return LunarPhaseModel(
+        degrees_between_s_m=degrees_between,
+        moon_phase=moon_phase,
+        moon_emoji=get_moon_emoji_from_phase_int(moon_phase),
+        moon_phase_name=get_moon_phase_name_from_phase_int(moon_phase)
+    )
 
 
 def circular_sort(degrees: list[Union[int, float]]) -> list[Union[int, float]]:
     """
-    Sort a list of degrees in a circular manner, starting from the first element
-    and progressing clockwise around the circle.
+    Sort degrees in circular clockwise progression starting from the first element.
 
     Args:
-        degrees: A list of numeric values representing degrees
+        degrees: List of numeric degree values
 
     Returns:
-        A list sorted based on circular clockwise progression from the first element
+        List sorted by clockwise distance from the first element
 
     Raises:
         ValueError: If the list is empty or contains non-numeric values
@@ -445,14 +483,16 @@ def circular_sort(degrees: list[Union[int, float]]) -> list[Union[int, float]]:
 
 def inline_css_variables_in_svg(svg_content: str) -> str:
     """
-    Process an SVG string to inline all CSS custom properties.
+    Replace CSS custom properties (variables) with their values in SVG content.
+
+    Extracts CSS variables from style blocks, replaces var() references with actual values,
+    and removes all style blocks from the SVG.
 
     Args:
-        svg_content (str): The original SVG string with CSS variables
+        svg_content: The original SVG string with CSS variables
 
     Returns:
-        str: The modified SVG with all CSS variables replaced by their values
-             and all style blocks removed
+        Modified SVG with CSS variables inlined and style blocks removed
     """
     # Find and extract CSS custom properties from style tags
     css_variable_map = {}
@@ -473,6 +513,15 @@ def inline_css_variables_in_svg(svg_content: str) -> str:
 
     # Function to replace var() references with their actual values
     def replace_css_variable_reference(match):
+        """
+        Replace CSS variable references with their actual values.
+
+        Args:
+            match: Regular expression match object containing variable name and optional fallback.
+
+        Returns:
+            str: The resolved CSS variable value or fallback value.
+        """
         variable_name = match.group(1).strip()
         fallback_value = match.group(2) if match.group(2) else None
 
@@ -490,8 +539,238 @@ def inline_css_variables_in_svg(svg_content: str) -> str:
     # This handles nested variables or variables that reference other variables
     processed_svg = svg_without_style_blocks
     while variable_usage_pattern.search(processed_svg):
-        processed_svg = variable_usage_pattern.sub(
-            lambda m: replace_css_variable_reference(m), processed_svg
-        )
+        processed_svg = variable_usage_pattern.sub(lambda m: replace_css_variable_reference(m), processed_svg)
 
     return processed_svg
+
+
+def datetime_to_julian(dt: datetime) -> float:
+    """
+    Convert a Python datetime object to Julian Day Number.
+
+    Args:
+        dt: The datetime object to convert
+
+    Returns:
+        The corresponding Julian Day Number (JD) as a float
+    """
+    # Extract year, month and day
+    year = dt.year
+    month = dt.month
+    day = dt.day
+
+    # Adjust month and year according to the conversion formula
+    if month <= 2:
+        year -= 1
+        month += 12
+
+    # Calculate century and year in century
+    a = year // 100
+    b = 2 - a + (a // 4)
+
+    # Calculate the Julian day
+    jd = int(365.25 * (year + 4716)) + int(30.6001 * (month + 1)) + day + b - 1524.5
+
+    # Add the time portion
+    hour = dt.hour
+    minute = dt.minute
+    second = dt.second
+    microsecond = dt.microsecond
+
+    jd += (hour + minute / 60 + second / 3600 + microsecond / 3600000000) / 24
+
+    return jd
+
+
+def julian_to_datetime(jd):
+    """
+    Convert a Julian Day Number to a Python datetime object.
+
+    Args:
+        jd: Julian Day Number as a float
+
+    Returns:
+        The corresponding datetime object
+    """
+    # Add 0.5 to the Julian day to adjust for noon-based Julian day
+    jd_plus = jd + 0.5
+
+    # Integer and fractional parts
+    Z = int(jd_plus)
+    F = jd_plus - Z
+
+    # Calculate alpha
+    if Z < 2299161:
+        A = Z  # Julian calendar
+    else:
+        alpha = int((Z - 1867216.25) / 36524.25)
+        A = Z + 1 + alpha - int(alpha / 4)  # Gregorian calendar
+
+    # Calculate B
+    B = A + 1524
+
+    # Calculate C
+    C = int((B - 122.1) / 365.25)
+
+    # Calculate D
+    D = int(365.25 * C)
+
+    # Calculate E
+    E = int((B - D) / 30.6001)
+
+    # Calculate day and month
+    day = B - D - int(30.6001 * E) + F
+
+    # Integer part of day
+    day_int = int(day)
+
+    # Fractional part converted to hours, minutes, seconds, microseconds
+    day_frac = day - day_int
+    hours = int(day_frac * 24)
+    minutes = int((day_frac * 24 - hours) * 60)
+    seconds = int((day_frac * 24 * 60 - hours * 60 - minutes) * 60)
+    microseconds = int(((day_frac * 24 * 60 - hours * 60 - minutes) * 60 - seconds) * 1000000)
+
+    # Calculate month
+    if E < 14:
+        month = E - 1
+    else:
+        month = E - 13
+
+    # Calculate year
+    if month > 2:
+        year = C - 4716
+    else:
+        year = C - 4715
+
+    # Create and return datetime object
+    return datetime(year, month, day_int, hours, minutes, seconds, microseconds)
+
+
+def get_house_name(house_number: int) -> Houses:
+    """
+    Convert a house number to its corresponding house name.
+
+    Args:
+        house_number: House number (1-12)
+
+    Returns:
+        The house name
+
+    Raises:
+        ValueError: If house_number is not in range 1-12
+    """
+    house_names: dict[int, Houses] = {
+        1: "First_House",
+        2: "Second_House",
+        3: "Third_House",
+        4: "Fourth_House",
+        5: "Fifth_House",
+        6: "Sixth_House",
+        7: "Seventh_House",
+        8: "Eighth_House",
+        9: "Ninth_House",
+        10: "Tenth_House",
+        11: "Eleventh_House",
+        12: "Twelfth_House",
+    }
+
+    name = house_names.get(house_number, None)
+    if name is None:
+        raise ValueError(f"Invalid house number: {house_number}")
+
+    return name
+
+
+def get_house_number(house_name: Houses) -> int:
+    """
+    Convert a house name to its corresponding house number.
+
+    Args:
+        house_name: The house name
+
+    Returns:
+        House number (1-12)
+
+    Raises:
+        ValueError: If house_name is not recognized
+    """
+    house_numbers: dict[Houses, int] = {
+        "First_House": 1,
+        "Second_House": 2,
+        "Third_House": 3,
+        "Fourth_House": 4,
+        "Fifth_House": 5,
+        "Sixth_House": 6,
+        "Seventh_House": 7,
+        "Eighth_House": 8,
+        "Ninth_House": 9,
+        "Tenth_House": 10,
+        "Eleventh_House": 11,
+        "Twelfth_House": 12,
+    }
+
+    number = house_numbers.get(house_name, None)
+    if number is None:
+        raise ValueError(f"Invalid house name: {house_name}")
+
+    return number
+
+
+def find_common_active_points(first_points: list[AstrologicalPoint], second_points: list[AstrologicalPoint]) -> list[AstrologicalPoint]:
+    """
+    Find astrological points that appear in both input lists.
+
+    Args:
+        first_points: First list of astrological points
+        second_points: Second list of astrological points
+
+    Returns:
+        List of points common to both input lists (without duplicates)
+    """
+    common_points = list(set(first_points) & set(second_points))
+
+    return common_points
+
+
+def distribute_percentages_to_100(values: dict[str, float]) -> dict[str, int]:
+    """
+    Distribute percentages so they sum to exactly 100.
+
+    This function uses a largest remainder method to ensure that
+    the percentage total equals 100 even after rounding.
+
+    Args:
+        values: Dictionary with keys and their raw percentage values
+
+    Returns:
+        Dictionary with the same keys and integer percentages that sum to 100
+    """
+    if not values:
+        return {}
+
+    total = sum(values.values())
+    if total == 0:
+        return {key: 0 for key in values.keys()}
+
+    # Calculate base percentages
+    percentages = {key: value * 100 / total for key, value in values.items()}
+
+    # Get integer parts and remainders
+    integer_parts = {key: int(value) for key, value in percentages.items()}
+    remainders = {key: percentages[key] - integer_parts[key] for key in percentages.keys()}
+
+    # Calculate how many we need to add to reach 100
+    current_sum = sum(integer_parts.values())
+    needed = 100 - current_sum
+
+    # Sort by remainder (largest first) and add 1 to the largest remainders
+    sorted_by_remainder = sorted(remainders.items(), key=lambda x: x[1], reverse=True)
+
+    result = integer_parts.copy()
+    for i in range(needed):
+        if i < len(sorted_by_remainder):
+            key = sorted_by_remainder[i][0]
+            result[key] += 1
+
+    return result