}Dj;\hUdZddlmZmZmZmZmZmZmZm Z ddl m Z m Z m Z mZmZddlmZmZmZmZddlmZmZmZmZmZmZmZddlZddlZddlmZee Z!iddd d d d d ddddddddddddddddddd d!d"d#d$d%d&d'd(d)d*d+d,Z"e#e$e%fe&d-<ed.d/d0d1d2ed3d4d5d6d 2ed7d8d9d:d 2ed;d/dd4d0d?d2ed@d8d5dAd2edBd/d9dCd2edDd4dded`e.fdZ?de.d`efdZ@de$d`e$fdZAde#e$e.fd`e#e$e%ffdZBde.de.d`efdZCycc}}w)a Kerykeion Utilities Module This module provides utility functions for astrological calculations including: - Zodiac position conversions and validations - House position determinations - Lunar phase calculations - Angular mathematics (circular mean, sorting) - Date/time conversions (Julian Day) - SVG processing utilities Author: Giacomo Battaglia Copyright: (C) 2025 Kerykeion Project License: AGPL-3.0 )KerykeionPointModelKerykeionExceptionZodiacSignModelAstrologicalSubjectModelLunarPhaseModelCompositeSubjectModelPlanetReturnModel ZodiacType)LunarPhaseEmojiLunarPhaseName PointTypeAstrologicalPointHouses)UnionOptionalget_argscast)DEBUGINFOWARNINGERRORCRITICAL basicConfig getLoggerN)datetimeSunMoonMercuryVenusMarsJupiterSaturnUranusNeptunePluto Mean_North_Lunar_Node True_North_Lunar_Node Mean_South_Lunar_NodeiTrue_South_Lunar_NodeiLChiron Mean_Lilith Ascendanti&i&i&i&) Descendant Medium_Coeli Imum_Coeli_POINT_NUMBER_MAPAriCardinalFireu♈️)signqualityelementemojisign_numTauFixedEarthu♉️GemMutableAiru♊️CanWateru♋️Leou♌️Viru♍️Libu♎️Scou♏️Sagu♐️Capu♑️Aquu♒️Pisu♓️) rrr r"r$r&r(r*r,r.r0r2 _ZODIAC_SIGNS First_House Second_House Third_House Fourth_House Fifth_House Sixth_House Seventh_House Eighth_House Ninth_House Tenth_HouseEleventh_House Twelfth_House) rr r"r$r&r(r*r,r.r0r2r8 _HOUSE_NAMES_HOUSE_NUMBERSlevelreturnc|xsdjj}tttt t d}|j|t}td|tj|y)z Configure the root logger for consistent formatting across the library. Args: level: Logging level as string (debug, info, warning, error, critical). Case-insensitive. Defaults to INFO if invalid. )debuginfowarningerrorcriticalz4%(asctime)s - %(name)s - %(levelname)s - %(message)s)formatreN) striplowerrrrrrgetrloggersetLevel)renormalized_level level_mapselected_levels _/var/www/html/Astrologybackend/backend/venv/lib/python3.12/site-packages/kerykeion/utilities.py setup_loggingrxqse **,224 !I]]#3T:NE OON#valuec|j}|dvrttdS|dk(rttdStdj |)a 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' )tropicaltropicTropicalsiderealSiderealz'{value}' is not a valid zodiac type. Accepted values are: Tropical, Sidereal (case-insensitive, 'tropic' also accepted as legacy).rz)rprr ValueErrorrn)rz value_lowers rwnormalize_zodiac_typersZ0++-K,,J ++  "J ++ DDJFQVFDW  rynamech tt|S#t$r}td||d}~wwxYw)a. Convert an astrological point name to its corresponding numerical identifier. 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 z)Error in getting number from name! Name: N)r=strKeyErrorr)rexcs rwget_number_from_namers?^ T++ ^ #LTF!STZ]]^s 1,1degree point_typespeed declination magnitudec|dkr|dz}|dk\rtd|t|dz}|dz}t|}t||j|j |j |j|||j|||| S)a 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) magnitude: The apparent visual magnitude for fixed stars (optional) Returns: A KerykeionPointModel with calculated zodiac sign, position, and properties Raises: KerykeionException: If the degree is >= 360 after normalization rhz)Error in calculating positions! Degrees: ) rrBrCrArEpositionabs_posrDrrrr) rintrVrrBrCrArErD) rrrrrr sign_index sign_degree zodiac_signs rwget_kerykeion_point_from_degreers4z# } #LVH!UVVVr\"J2+K +K  ####   %%  ry start_angle end_angle candidatecd}||}||}||}||z dz}|dkDrtd|tj||ddrytj||ddry ||z dz}||kS) ur Check if a candidate angle lies on the clockwise arc from start to end angle. Args: start_angle: Starting angle in degrees end_angle: Ending angle in degrees candidate: Angle to check Returns: True if candidate is on the clockwise arc from start to end Raises: KerykeionException: If the arc exceeds 180° c |dzS)Nrrs rwz"is_point_between..s eckryruNThe angle between start and end point is not allowed to exceed 180°, yet is: g& .>g-q=)rel_tolabs_tolTF)rmathisclose) rrr normalizestartendtargetspandistance_from_starts rwis_point_betweenrs"*I k "E I C y !F %K3 D cz #qrvqw!xyy ||FE4? ||FCu=!E>S0  %%ry planet_degreehouses_degree_ut_listctt}tt|D]/}||}||dzt|z}t |||s*||cSt d|d|)am Determine which house contains a planet based on its degree position. Args: planet_degree: The planet's position in degrees (0-360) houses_degree_ut_list: List of house cusp degrees Returns: The house name containing the planet Raises: ValueError: If the planet's position doesn't fall within any house range rz$Error in house calculation, planet: z , houses: )rrrangelenrr)rr house_namesi start_degree end_degrees rwget_planet_houser"s}6"K 3{# $",Q/ *AES9N5O+OP L*m Dq> ! " ;M?*UjTkl mmry house_numbercRtj|d}|td||S)z 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 NzInvalid house number: )rcrqr)rrs rwget_house_namer<s3   L$ /D |1,@AA Kry house_namecRtj|d}|td||S)z 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 NzInvalid house name: )rdrqr)rnumbers rwget_house_numberrOs3   D 1F ~/ |<== Mrysubjectcpg}|jD]$}|j||j&|S)z 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_names_listappendrp)rhouses_absolute_position_listhouses rwget_houses_listrbsB%'!**E%,,WU[[]-CDE )(rycpg}|jD]$}|j||j&|S)z 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 ) active_pointsrrp)rplanets_absolute_position_listplanets rw&get_available_astrological_points_listrusB&("''G&--gflln.EFG *)ry first_points second_pointscBtt|t|zS)a 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) )sortedset)rrs rwfind_common_active_pointsrs #l#c-&88 99ryphasec|dk(ry|dkryd|cxkrdkry|dkry|dk(ry|d kry d |cxkrd kry |d krytd|)a Get the index for lunar phase lookup based on phase number. Args: phase: The lunar phase number (1-28) Returns: Index (0-7) for lunar phase lookup arrays Raises: KerykeionException: If phase is outside valid range rrr*r.r r"r$r&r(z)Error in lunar phase calculation! Phase: )r)rs rw_get_lunar_phase_indexrs{ z  eq   "  u    " #LUG!TUUryc@tt}t|}||S)z Get the emoji representation of a lunar phase. Args: phase: The lunar phase number (0-28) Returns: The corresponding emoji for the lunar phase Raises: KerykeionException: If phase is outside valid range )rr r)rlunar_phase_emojisindexs rwget_moon_emoji_from_phase_intrs$"/2 "5 )E e $$ryc@tt}t|}||S)a Get the name of a lunar phase from its numerical value. Args: phase: The lunar phase number (0-28) Returns: The corresponding name for the lunar phase Raises: KerykeionException: If phase is outside valid range )rr r)rlunar_phase_namesrs rw"get_moon_phase_name_from_phase_intrs$!0 "5 )E U ##rylatitudecz|dkDrd}tjd|S|dkrd}tjd|S)u' 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° gP@u:Latitude capped at 66° to keep house calculations stable.gPu;Latitude capped at -66° to keep house calculations stable.)rrrj)rs rwcheck_and_adjust_polar_latitudersE$ PQ O E  QR Oryfirst_positionsecond_positionctjtj|tjtj|zdz }tjtj|tjtj|zdz }tjtj ||}|dkr|dz }|S)u Calculate the circular mean of two angular positions. This method correctly handles positions that cross the 0°/360° boundary, avoiding errors that occur with simple arithmetic means. Args: first_position: First angular position in degrees (0-360) second_position: Second angular position in degrees (0-360) Returns: The circular mean position in degrees (0-360) r rr)rcosradianssindegreesatan2)rrxy mean_positions rw circular_meanrs $,,~. /$((4<<;X2Y Y]^^A $,,~. /$((4<<;X2Y Y]^^ALLAq!12Mq ryrc||s tdtd|Ds6td|D}td|dt|jt |dkr|j S|ddtttfd tttfffd }|dd }t|| }g|zS) a7 Sort degrees in circular clockwise progression starting from the first element. Args: degrees: List of numeric degree values Returns: List sorted by clockwise distance from the first element Raises: ValueError: If the list is empty or contains non-numeric values zInput list cannot be emptyc3HK|]}t|ttfywN isinstancerfloat).0rs rw z circular_sort..$sFFz&3,/Fs "c3NK|]}t|ttfr|ywrr)rds rwrz circular_sort..%sMQAU|1LqMs%%z%All elements must be numeric, found: z of type rranglerfc:dz}|dz}||z }|dkr|dz }|S)Nrrr)rref_norm angle_normdistance references rwclockwise_distancez)circular_sort..clockwise_distance-s4s?S[ ( a< OHryN)key) rallnexttype__name__rcopyrrrr)rinvalidr remainingsorted_remainingrs @rw circular_sortrs 566 FgF FM'MM@ SWX_S`SiSiRjkll 7|q||~ I%U "3c5j8I Ii-?@ ;) ))rydtcx|j}|j}|j}|dkr |dz}|dz }|dz}d|z |dzz}td|dzztd|dzzz|z|zd z }|j}|j }|j } |j} |||d z z| d z z| d z zd z z }|S)z 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 r rr8dr$v@laTR'>@gҗ@<il$'-)yearmonthdayrhourminutesecond microsecond) rrrrabjdrrrrs rwdatetime_to_julianr@s 77D HHE &&C z      A AaA Vtd{ # $s7eai+@'A AC G! Kf TB 77D YYF YYF..K4&2+  - j0H HB NNB Iryrc j|dz}t|}||z }|dkr|}n(t|dz dz }|dz|zt|dz z }|dz}t|dz d z }td |z}t||z d z } ||z td | zz |z} t| } | | z } t| d z} t| d z| z d z}t| d zd z| d zz |z d z}t| d zd z| d zz |z d z|z d z}| dkr| dz }n| dz }|dkDr|dz }n|dz }t||| | |||S)z Convert a Julian Day Number to a Python datetime object. Args: jd: Julian Day Number as a float Returns: The corresponding datetime object g?i#g@}(.*?)z!--([a-zA-Z0-9_-]+)\s*:\s*([^;]+);rr z--rhc|jdj}|jdr|jdnd}|vr|S|r|jSy)Nrr"rh)groupro)match variable_namefallback_valuecss_variable_maps rwreplace_css_variable_referencezCinline_css_variables_in_svg..replace_css_variable_references[ A,,. +0;;q>Qt , ,#M2 2 !'') )ryz(var\(\s*(--[\w-]+)\s*(,\s*([^)]+))?\s*\)c|Srr)mr5s rwrz-inline_css_variables_in_svg..s=[\]=^ry) recompileDOTALLfindallfinditerr0rosubsearch) r-style_tag_pattern style_blocks style_blockcss_variable_patternr1r2variable_valuesvg_without_style_blocksvariable_usage_pattern processed_svgr4r5s @@rwinline_css_variables_in_svgrGs #=ryyI$,,[9L#D !zz*NO)22;? DE!KKNM"[[^113N5C r-1 2 DD 144RE  ZZ(ST,M ' ' 6.223^`mn  ! ' ' 6 ryvaluesc|siSt|j}|dk(r|jDcic]}|dc}S|jDcic]\}}||dz|z }}}|jDcic]\}}|t |}}}|jDcic]}|||||z }}t|j}d|z }t |jdd} |j } t|D]&} | t| ks| | d}| |xxdz cc<(| Scc}wcc}}wcc}}wcc}w)ac 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 rr c |dS)Nrr)rs rwrz/distribute_percentages_to_100..s 1Q4ryT)rreverser) sumrHkeysitemsrrrrr) rHtotalrrz percentages integer_parts remainders current_sumneededsorted_by_remainderresultrs rwdistribute_percentages_to_100rWsX    E z"(++-03Q00>DllnM U3 e++MKM7B7H7H7JKeS#e*_KMKHSHXHXHZ[#{3'-*<<<[J[m**,-K ; F !1!1!3QUV    !F 6] s&' '%a(+C 3K1 K M#1MK[s D?E>E )E moon_abs_pos sun_abs_poscz||z dz}d}t||zdz}t||t|t|S)a Calculate lunar phase information from Sun and Moon positions. Args: moon_abs_pos: Absolute position of the Moon in degrees sun_abs_pos: Absolute position of the Sun in degrees Returns: LunarPhaseModel containing phase data, emoji, and name rgn۶m۶)@r)degrees_between_s_m moon_phase moon_emojimoon_phase_name)rrrr)rXrYdegrees_betweenstepr\s rwcalculate_moon_phaserasQ$k1S8O D_,-1J +0<::F  ry)NNN)D__doc__kerykeion.schemasrrrrrrr r kerykeion.schemas.kr_literalsr r r rrtypingrrrrloggingrrrrrrrrr8rrrrr=dictrr__annotations__rVrcrNrdrxrrrrboolrlistrrrrrrrrrrrrrr,rGrWra)kvs00rwrmsw   32QQQ  8 % 1% A%q% Q %  A % q % a% a%q% Q%R%R%T%T%  b!%"2#%$%%&+%4S>4E:vX`abE7G8^_`E9e8^_`E:whabcE7F(]^_E9gX`abE:uH_`aE7G8^_`E9fH_`aE:whabcUGU(]_`UIwhacd - tC() " # d3; 7C6H6H6J$KdaQT$KVS[!K$$$<" " " J^0^S^."#'!% 1 #u* 1 !6) *11 E? 1 % 1  11r&sEz"&/4S%Z/@&MRSVX]S]M^& &DnE#u*$5ndnW]n4&C&) +-BDUU V) )&*4L*QUViQj*" :() ::>?P:Q :  :*V#V#VB%%%$$c$n$$e8%U "3eCQVJFW\a0$*4c5j 12$*tE#u*