kerykeion 5.0.0a9__py3-none-any.whl → 5.1.8__py3-none-any.whl

kerykeion/utilities.py

@@ -1,4 +1,10 @@
-from kerykeion.kr_types import (
+"""
+Author: Giacomo Battaglia
+Copyright: (C) 2025 Kerykeion Project
+License: AGPL-3.0
+"""
+
+from kerykeion.schemas import (
     KerykeionPointModel,
     KerykeionException,
     ZodiacSignModel,
@@ -6,82 +12,146 @@ from kerykeion.kr_types import (
     LunarPhaseModel,
     CompositeSubjectModel,
     PlanetReturnModel,
+    ZodiacType,
+)
+from kerykeion.schemas.kr_literals import (
+    LunarPhaseEmoji,
+    LunarPhaseName,
+    PointType,
+    AstrologicalPoint,
+    Houses,
 )
-from kerykeion.kr_types.kr_literals import LunarPhaseEmoji, LunarPhaseName, PointType, AstrologicalPoint, Houses
-from typing import Union, get_args, TYPE_CHECKING
-import logging
+from typing import Union, Optional, get_args, cast
+from logging import DEBUG, INFO, WARNING, ERROR, CRITICAL, basicConfig, getLogger
 import math
 import re
 from datetime import datetime
 
-if TYPE_CHECKING:
-    from kerykeion import AstrologicalSubjectFactory
 
+logger = getLogger(__name__)
 
-def get_number_from_name(name: AstrologicalPoint) -> int:
-    """Utility function, gets planet id from the name."""
-
-    if name == "Sun":
-        return 0
-    elif name == "Moon":
-        return 1
-    elif name == "Mercury":
-        return 2
-    elif name == "Venus":
-        return 3
-    elif name == "Mars":
-        return 4
-    elif name == "Jupiter":
-        return 5
-    elif name == "Saturn":
-        return 6
-    elif name == "Uranus":
-        return 7
-    elif name == "Neptune":
-        return 8
-    elif name == "Pluto":
-        return 9
-    elif name == "Mean_Node":
-        return 10
-    elif name == "True_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":
-        return 1000
-    elif name == "True_South_Node":
-        return 1100
-    elif name == "Chiron":
-        return 15
-    elif name == "Mean_Lilith":
-        return 12
-    elif name == "Ascendant":  # TODO: Is this needed?
-        return 9900
-    elif name == "Descendant":  # TODO: Is this needed?
-        return 9901
-    elif name == "Medium_Coeli":  # TODO: Is this needed?
-        return 9902
-    elif name == "Imum_Coeli":  # TODO: Is this needed?
-        return 9903
+def normalize_zodiac_type(value: str) -> ZodiacType:
+    """
+    Normalize a zodiac type string to its canonical representation.
+
+    Handles case-insensitive matching and legacy formats like "tropic" or "Tropic",
+    automatically converting them to the canonical forms "Tropical" or "Sidereal".
+
+    Args:
+        value: Input zodiac type string (case-insensitive).
+
+    Returns:
+        ZodiacType: Canonical zodiac type ("Tropical" or "Sidereal").
+
+    Raises:
+        ValueError: If `value` is not a recognized zodiac type.
+
+    Examples:
+        >>> normalize_zodiac_type("tropical")
+        'Tropical'
+        >>> normalize_zodiac_type("Tropic")
+        'Tropical'
+        >>> normalize_zodiac_type("SIDEREAL")
+        'Sidereal'
+    """
+    # Normalize to lowercase for comparison
+    value_lower = value.lower()
+
+    # Map legacy and case-insensitive variants to canonical forms
+    if value_lower in ("tropical", "tropic"):
+        return cast(ZodiacType, "Tropical")
+    elif value_lower == "sidereal":
+        return cast(ZodiacType, "Sidereal")
     else:
-        raise KerykeionException(f"Error in getting number from name! Name: {name}")
+        raise ValueError(
+            "'{value}' is not a valid zodiac type. Accepted values are: Tropical, Sidereal "
+            "(case-insensitive, 'tropic' also accepted as legacy).".format(value=value)
+        )
+
+_POINT_NUMBER_MAP: dict[str, int] = {
+    "Sun": 0,
+    "Moon": 1,
+    "Mercury": 2,
+    "Venus": 3,
+    "Mars": 4,
+    "Jupiter": 5,
+    "Saturn": 6,
+    "Uranus": 7,
+    "Neptune": 8,
+    "Pluto": 9,
+    "Mean_North_Lunar_Node": 10,
+    "True_North_Lunar_Node": 11,
+    # Swiss Ephemeris has no dedicated IDs for the south nodes; we reserve high values.
+    "Mean_South_Lunar_Node": 1000,
+    "True_South_Lunar_Node": 1100,
+    "Chiron": 15,
+    "Mean_Lilith": 12,
+    "Ascendant": 9900,
+    "Descendant": 9901,
+    "Medium_Coeli": 9902,
+    "Imum_Coeli": 9903,
+}
+
+# Logging helpers
+def setup_logging(level: str) -> None:
+    """Configure the root logger so demo scripts share the same formatting."""
+    normalized_level = (level or "").strip().lower()
+    level_map: dict[str, int] = {
+        "debug": DEBUG,
+        "info": INFO,
+        "warning": WARNING,
+        "error": ERROR,
+        "critical": CRITICAL,
+    }
 
+    selected_level = level_map.get(normalized_level, INFO)
+    basicConfig(
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        level=selected_level,
+    )
+    logger.setLevel(selected_level)
 
-def get_kerykeion_point_from_degree(
-    degree: Union[int, float], name: Union[AstrologicalPoint, Houses], point_type: PointType
-) -> KerykeionPointModel:
+
+
+
+def get_number_from_name(name: AstrologicalPoint) -> int:
     """
-    Returns a KerykeionPointModel object based on the given degree.
+    Convert an astrological point name to its corresponding numerical identifier.
 
     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.
+        name: The name of the astrological point
+
+    Returns:
+        The numerical identifier used in Swiss Ephemeris calculations
 
     Raises:
-        KerykeionException: If the degree is not within the valid range (0-360).
+        KerykeionException: If the name is not recognized
+    """
+
+    try:
+        return _POINT_NUMBER_MAP[str(name)]
+    except KeyError as exc:  # pragma: no cover - defensive branch
+        raise KerykeionException(f"Error in getting number from name! Name: {name}") from exc
+
+
+def get_kerykeion_point_from_degree(
+    degree: Union[int, float], name: Union[AstrologicalPoint, Houses], point_type: PointType, speed: Optional[float] = None, declination: Optional[float] = None
+) -> KerykeionPointModel:
+    """
+    Create a KerykeionPointModel from a degree position.
+
+    Args:
+        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:
@@ -108,7 +178,6 @@ def get_kerykeion_point_from_degree(
     sign_index = int(degree // 30)
     sign_degree = degree % 30
     zodiac_sign = ZODIAC_SIGNS[sign_index]
-
     return KerykeionPointModel(
         name=name,
         quality=zodiac_sign.quality,
@@ -119,91 +188,45 @@ def get_kerykeion_point_from_degree(
         abs_pos=degree,
         emoji=zodiac_sign.emoji,
         point_type=point_type,
+        speed=speed,
+        declination=declination,
     )
 
+# Angular helpers
+def is_point_between(start_angle: Union[int, float], end_angle: Union[int, float], candidate: Union[int, float]) -> bool:
+    """Return True when ``candidate`` lies on the clockwise arc from ``start_angle`` to ``end_angle``."""
 
-def setup_logging(level: str) -> None:
-    """
-    Setup logging for testing.
-
-    Args:
-        level: Log level as a string, options: debug, info, warning, error
-    """
-    logging_options: dict[str, int] = {
-        "debug": logging.DEBUG,
-        "info": logging.INFO,
-        "warning": logging.WARNING,
-        "error": logging.ERROR,
-        "critical": logging.CRITICAL,
-    }
-    format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-    loglevel: int = logging_options.get(level, logging.INFO)
-    logging.basicConfig(format=format, level=loglevel)
-
-
-def is_point_between(
-    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°.
-
-    Args:
-        - start_point: The first point on the circle.
-        - end_point: The second point on the circle.
-        - evaluated_point: The point to check.
-
-    Returns:
-        - True if evaluated_point is between start_point and end_point, False otherwise.
-    """
-
-    # Normalize angles to [0, 360)
-    start_point = start_point % 360
-    end_point = end_point % 360
-    evaluated_point = evaluated_point % 360
-
-    # Compute angular difference
-    angular_difference = math.fmod(end_point - start_point + 360, 360)
+    normalize = lambda value: value % 360
 
-    # 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:
+    start = normalize(start_angle)
+    end = normalize(end_angle)
+    target = normalize(candidate)
+    span = (end - start) % 360
+    if span > 180:
         raise KerykeionException(
-            f"The angle between start and end point is not allowed to exceed 180°, yet is: {angular_difference}"
+            f"The angle between start and end point is not allowed to exceed 180°, yet is: {span}"
         )
-
-    # 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
-    # should really be same value. This case is captured later below by the term 0 <= p1_p3.
-    if evaluated_point == start_point:
+    if target == start:
         return True
-
-    # Handle explicitly when evaluated_point == end_point
-    if evaluated_point == end_point:
+    if target == end:
         return False
+    distance_from_start = (target - start) % 360
+    return distance_from_start < span
 
-    # Compute angular differences for evaluation
-    p1_p3 = math.fmod(evaluated_point - start_point + 360, 360)
-
-    # Check if point lies in the interval
-    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:
+# House helpers
+def get_planet_house(planet_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_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)
@@ -213,22 +236,25 @@ def get_planet_house(planet_position_degree: Union[int, float], houses_degree_ut
         start_degree = houses_degree_ut_list[i]
         end_degree = houses_degree_ut_list[(i + 1) % len(houses_degree_ut_list)]
 
-        if is_point_between(start_degree, end_degree, planet_position_degree):
+        if is_point_between(start_degree, end_degree, planet_degree):
             return house_names[i]
 
     # If no house is found, raise an error
-    raise ValueError(f"Error in house calculation, planet: {planet_position_degree}, houses: {houses_degree_ut_list}")
+    raise ValueError(f"Error in house calculation, planet: {planet_degree}, houses: {houses_degree_ut_list}")
 
 
 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)
@@ -258,13 +284,16 @@ def get_moon_emoji_from_phase_int(phase: int) -> LunarPhaseEmoji:
 
 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)
 
@@ -293,16 +322,23 @@ 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
-        logging.info("Polar circle override for houses, using 66 degrees")
+        logger.info("Latitude capped at 66° to keep house calculations stable.")
 
     elif latitude < -66.0:
         latitude = -66.0
-        logging.info("Polar circle override for houses, using -66 degrees")
+        logger.info("Latitude capped at -66° to keep house calculations stable.")
 
     return latitude
 
@@ -311,7 +347,13 @@ 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:
@@ -324,8 +366,13 @@ 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.active_points:
@@ -336,17 +383,17 @@ def get_available_astrological_points_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
@@ -361,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
 
@@ -380,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
@@ -458,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 = {}
@@ -486,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
 
@@ -510,13 +546,13 @@ def inline_css_variables_in_svg(svg_content: str) -> str:
 
 def datetime_to_julian(dt: datetime) -> float:
     """
-    Converts a Python datetime object to Julian day.
+    Convert a Python datetime object to Julian Day Number.
 
     Args:
-        dt: A datetime object
+        dt: The datetime object to convert
 
     Returns:
-        float: The corresponding Julian day (JD)
+        The corresponding Julian Day Number (JD) as a float
     """
     # Extract year, month and day
     year = dt.year
@@ -548,13 +584,13 @@ def datetime_to_julian(dt: datetime) -> float:
 
 def julian_to_datetime(jd):
     """
-    Converts a Julian day to a Python datetime object.
+    Convert a Julian Day Number to a Python datetime object.
 
     Args:
-        jd: Julian day number (float)
+        jd: Julian Day Number as a float
 
     Returns:
-        datetime: The corresponding datetime object
+        The corresponding datetime object
     """
     # Add 0.5 to the Julian day to adjust for noon-based Julian day
     jd_plus = jd + 0.5
@@ -613,13 +649,16 @@ def julian_to_datetime(jd):
 
 def get_house_name(house_number: int) -> Houses:
     """
-    Returns the name of the house based on its number.
+    Convert a house number to its corresponding house name.
 
     Args:
         house_number: House number (1-12)
 
     Returns:
-        Name of the house
+        The house name
+
+    Raises:
+        ValueError: If house_number is not in range 1-12
     """
     house_names: dict[int, Houses] = {
         1: "First_House",
@@ -645,13 +684,16 @@ def get_house_name(house_number: int) -> Houses:
 
 def get_house_number(house_name: Houses) -> int:
     """
-    Returns the number of the house based on its name.
+    Convert a house name to its corresponding house number.
 
     Args:
-        house_name: Name of the house
+        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,
@@ -677,15 +719,58 @@ def get_house_number(house_name: Houses) -> int:
 
 def find_common_active_points(first_points: list[AstrologicalPoint], second_points: list[AstrologicalPoint]) -> list[AstrologicalPoint]:
     """
-    Find only the elements that are present in both lists.
+    Find astrological points that appear in both input lists.
 
     Args:
-        first_points: List of astrological points
-        second_points: List of astrological points
+        first_points: First list of astrological points
+        second_points: Second list of astrological points
 
     Returns:
-        List of elements common to both lists (without duplicates, order not guaranteed).
+        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