kerykeion 4.26.2__py3-none-any.whl → 5.0.0a2__py3-none-any.whl

kerykeion/utilities.py

@@ -1,15 +1,24 @@
-from kerykeion.kr_types import KerykeionPointModel, KerykeionException, ZodiacSignModel, AstrologicalSubjectModel, LunarPhaseModel
-from kerykeion.kr_types.kr_literals import LunarPhaseEmoji, LunarPhaseName, PointType, Planet, Houses, AxialCusps
+from kerykeion.kr_types import (
+    KerykeionPointModel,
+    KerykeionException,
+    ZodiacSignModel,
+    AstrologicalSubjectModel,
+    LunarPhaseModel,
+    CompositeSubjectModel,
+    PlanetReturnModel,
+)
+from kerykeion.kr_types.kr_literals import LunarPhaseEmoji, LunarPhaseName, PointType, AstrologicalPoint, Houses
 from typing import Union, get_args, TYPE_CHECKING
 import logging
 import math
 import re
+from datetime import datetime
 
 if TYPE_CHECKING:
-    from kerykeion import AstrologicalSubject
+    from kerykeion import AstrologicalSubjectFactory
 
 
-def get_number_from_name(name: Planet) -> int:
+def get_number_from_name(name: AstrologicalPoint) -> int:
     """Utility function, gets planet id from the name."""
 
     if name == "Sun":
@@ -45,20 +54,20 @@ def get_number_from_name(name: Planet) -> int:
         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
 ) -> KerykeionPointModel:
     """
     Returns a KerykeionPointModel object based on the given degree.
@@ -74,8 +83,11 @@ def get_kerykeion_point_from_degree(
     Returns:
         KerykeionPointModel: The model representing the celestial point.
     """
+    # 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 = {
@@ -109,6 +121,7 @@ def get_kerykeion_point_from_degree(
         point_type=point_type,
     )
 
+
 def setup_logging(level: str) -> None:
     """
     Setup logging for testing.
@@ -129,9 +142,7 @@ 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:
@@ -159,7 +170,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,7 +191,6 @@ 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.
@@ -243,6 +255,7 @@ 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.
@@ -255,11 +268,10 @@ def get_moon_phase_name_from_phase_int(phase: int) -> LunarPhaseName:
     """
     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 +293,8 @@ 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.
+    Utility function to check if the location is in the polar circle.
+    If it is, it sets the latitude to 66 or -66 degrees.
     """
     if latitude > 66.0:
         latitude = 66.0
@@ -295,28 +307,29 @@ 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.
     """
     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.
     """
     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
 
@@ -387,7 +400,7 @@ def calculate_moon_phase(moon_abs_pos: float, sun_abs_pos: float) -> LunarPhaseM
         "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)
+        "moon_phase_name": get_moon_phase_name_from_phase_int(moon_phase),
     }
 
     return LunarPhaseModel(**lunar_phase_dictionary)
@@ -490,8 +503,192 @@ 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:
+    """
+    Converts a Python datetime object to Julian day.
+
+    Args:
+        dt: A datetime object
+
+    Returns:
+        float: The corresponding Julian day (JD)
+    """
+    # 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):
+    """
+    Converts a Julian day to a Python datetime object.
+
+    Args:
+        jd: Julian day number (float)
+
+    Returns:
+        datetime: 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:
+    """
+    Returns the name of the house based on its number.
+
+    Args:
+        house_number: House number (1-12)
+
+    Returns:
+        Name of the house
+    """
+    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:
+    """
+    Returns the number of the house based on its name.
+
+    Args:
+        house_name: Name of the house
+
+    Returns:
+        House number (1-12)
+    """
+    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 the common astrological points between those available in the subject and those requested.
+
+        Args:
+            first_points: List of points available in the astrological subject
+            second_points: List of points requested by the user
+
+        Returns:
+            List containing only the requested points that are also available in the subject
+    """
+    common_points: list[AstrologicalPoint]
+    common_points = [point for point in second_points if point in first_points]
+
+    ignored_points = set(second_points) - set(common_points)
+
+    return common_points