39class AspectsFactory:
 40    """
 41    Unified factory class for creating both single chart and dual chart aspects analysis.
 42
 43    This factory provides methods to calculate all aspects within a single chart or
 44    between two charts. It consolidates the common functionality between different
 45    types of aspect calculations while providing specialized methods for each type.
 46
 47    The factory provides both comprehensive and filtered aspect lists based on orb settings
 48    and relevance criteria.
 49
 50    Key Features:
 51        - Calculates aspects within a single chart (natal, returns, composite, etc.)
 52        - Calculates aspects between two charts (synastry, transits, comparisons, etc.)
 53        - Filters aspects based on orb thresholds
 54        - Applies stricter orb limits for chart axes (ASC, MC, DSC, IC)
 55        - Supports multiple subject types (natal, composite, planetary returns)
 56
 57    Example:
 58        >>> # For single chart aspects (natal, returns, etc.)
 59        >>> johnny = AstrologicalSubjectFactory.from_birth_data("Johnny", 1963, 6, 9, 0, 0, "Owensboro", "US")
 60        >>> single_chart_aspects = AspectsFactory.single_chart_aspects(johnny)
 61        >>>
 62        >>> # For dual chart aspects (synastry, comparisons, etc.)
 63        >>> john = AstrologicalSubjectFactory.from_birth_data("John", 1990, 1, 1, 12, 0, "London", "GB")
 64        >>> jane = AstrologicalSubjectFactory.from_birth_data("Jane", 1992, 6, 15, 14, 30, "Paris", "FR")
 65        >>> dual_chart_aspects = AspectsFactory.dual_chart_aspects(john, jane)
 66    """
 67
 68    @staticmethod
 69    def single_chart_aspects(
 70        subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
 71        *,
 72        active_points: Optional[List[AstrologicalPoint]] = None,
 73        active_aspects: Optional[List[ActiveAspect]] = None,
 74    ) -> SingleChartAspectsModel:
 75        """
 76        Create aspects analysis for a single astrological chart.
 77
 78        This method calculates all astrological aspects (angular relationships)
 79        within a single chart. Can be used for any type of chart including:
 80        - Natal charts
 81        - Planetary return charts
 82        - Composite charts
 83        - Any other single chart type
 84
 85        Args:
 86            subject: The astrological subject for aspect calculation
 87
 88        Kwargs:
 89            active_points: List of points to include in calculations
 90            active_aspects: List of aspects with their orb settings
 91
 92        Returns:
 93            SingleChartAspectsModel containing all calculated aspects data
 94
 95        Example:
 96            >>> johnny = AstrologicalSubjectFactory.from_birth_data("Johnny", 1963, 6, 9, 0, 0, "Owensboro", "US")
 97            >>> chart_aspects = AspectsFactory.single_chart_aspects(johnny)
 98            >>> print(f"Found {len(chart_aspects.relevant_aspects)} relevant aspects")
 99        """
100        # Initialize settings and configurations
101        celestial_points = DEFAULT_CELESTIAL_POINTS_SETTINGS
102        aspects_settings = DEFAULT_CHART_ASPECTS_SETTINGS
103        axes_orbit_settings = DEFAULT_AXIS_ORBIT
104
105        # Set active aspects with default fallback
106        active_aspects_resolved = active_aspects if active_aspects is not None else DEFAULT_ACTIVE_ASPECTS
107
108        # Determine active points to use
109        if active_points is None:
110            active_points_resolved = subject.active_points
111        else:
112            active_points_resolved = find_common_active_points(
113                subject.active_points,
114                active_points,
115            )
116
117        return AspectsFactory._create_single_chart_aspects_model(
118            subject, active_points_resolved, active_aspects_resolved,
119            aspects_settings, axes_orbit_settings, celestial_points
120        )
121
122    @staticmethod
123    def dual_chart_aspects(
124        first_subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
125        second_subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
126        *,
127        active_points: Optional[List[AstrologicalPoint]] = None,
128        active_aspects: Optional[List[ActiveAspect]] = None,
129    ) -> DualChartAspectsModel:
130        """
131        Create aspects analysis between two astrological charts.
132
133        This method calculates all astrological aspects (angular relationships)
134        between planets and points in two different charts. Can be used for:
135        - Synastry (relationship compatibility)
136        - Transit comparisons
137        - Composite vs natal comparisons
138        - Any other dual chart analysis
139
140        Args:
141            first_subject: The first astrological subject
142            second_subject: The second astrological subject to compare with the first
143
144        Kwargs:
145            active_points: Optional list of celestial points to include in calculations.
146                          If None, uses common points between both subjects.
147            active_aspects: Optional list of aspect types with their orb settings.
148                           If None, uses default aspect configuration.
149
150        Returns:
151            DualChartAspectsModel: Complete model containing all calculated aspects data,
152                                  including both comprehensive and filtered relevant aspects.
153
154        Example:
155            >>> john = AstrologicalSubjectFactory.from_birth_data("John", 1990, 1, 1, 12, 0, "London", "GB")
156            >>> jane = AstrologicalSubjectFactory.from_birth_data("Jane", 1992, 6, 15, 14, 30, "Paris", "FR")
157            >>> synastry = AspectsFactory.dual_chart_aspects(john, jane)
158            >>> print(f"Found {len(synastry.relevant_aspects)} relevant aspects")
159        """
160        # Initialize settings and configurations
161        celestial_points = DEFAULT_CELESTIAL_POINTS_SETTINGS
162        aspects_settings = DEFAULT_CHART_ASPECTS_SETTINGS
163        axes_orbit_settings = DEFAULT_AXIS_ORBIT
164
165        # Set active aspects with default fallback
166        active_aspects_resolved = active_aspects if active_aspects is not None else DEFAULT_ACTIVE_ASPECTS
167
168        # Determine active points to use - find common points between both subjects
169        if active_points is None:
170            active_points_resolved = first_subject.active_points
171        else:
172            active_points_resolved = find_common_active_points(
173                first_subject.active_points,
174                active_points,
175            )
176
177        # Further filter with second subject's active points
178        active_points_resolved = find_common_active_points(
179            second_subject.active_points,
180            active_points_resolved,
181        )
182
183        return AspectsFactory._create_dual_chart_aspects_model(
184            first_subject, second_subject, active_points_resolved, active_aspects_resolved,
185            aspects_settings, axes_orbit_settings, celestial_points
186        )
187
188    @staticmethod
189    def _create_single_chart_aspects_model(
190        subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
191        active_points_resolved: List[AstrologicalPoint],
192        active_aspects_resolved: List[ActiveAspect],
193        aspects_settings: List[dict],
194        axes_orbit_settings: float,
195        celestial_points: List[dict]
196    ) -> SingleChartAspectsModel:
197        """
198        Create the complete single chart aspects model with all calculations.
199
200        Returns:
201            SingleChartAspectsModel containing all aspects data
202        """
203        all_aspects = AspectsFactory._calculate_single_chart_aspects(
204            subject, active_points_resolved, active_aspects_resolved, aspects_settings, celestial_points
205        )
206        relevant_aspects = AspectsFactory._filter_relevant_aspects(all_aspects, axes_orbit_settings)
207
208        return SingleChartAspectsModel(
209            subject=subject,
210            all_aspects=all_aspects,
211            relevant_aspects=relevant_aspects,
212            active_points=active_points_resolved,
213            active_aspects=active_aspects_resolved,
214        )
215
216    @staticmethod
217    def _create_dual_chart_aspects_model(
218        first_subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
219        second_subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
220        active_points_resolved: List[AstrologicalPoint],
221        active_aspects_resolved: List[ActiveAspect],
222        aspects_settings: List[dict],
223        axes_orbit_settings: float,
224        celestial_points: List[dict]
225    ) -> DualChartAspectsModel:
226        """
227        Create the complete dual chart aspects model with all calculations.
228
229        Args:
230            first_subject: First astrological subject
231            second_subject: Second astrological subject
232            active_points_resolved: Resolved list of active celestial points
233            active_aspects_resolved: Resolved list of active aspects with orbs
234            aspects_settings: Chart aspect configuration settings
235            axes_orbit_settings: Orb threshold for chart axes
236            celestial_points: Celestial points configuration
237
238        Returns:
239            DualChartAspectsModel: Complete model containing all aspects data
240        """
241        all_aspects = AspectsFactory._calculate_dual_chart_aspects(
242            first_subject, second_subject, active_points_resolved, active_aspects_resolved,
243            aspects_settings, celestial_points
244        )
245        relevant_aspects = AspectsFactory._filter_relevant_aspects(all_aspects, axes_orbit_settings)
246
247        return DualChartAspectsModel(
248            first_subject=first_subject,
249            second_subject=second_subject,
250            all_aspects=all_aspects,
251            relevant_aspects=relevant_aspects,
252            active_points=active_points_resolved,
253            active_aspects=active_aspects_resolved,
254        )
255
256    @staticmethod
257    def _calculate_single_chart_aspects(
258        subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
259        active_points: List[AstrologicalPoint],
260        active_aspects: List[ActiveAspect],
261        aspects_settings: List[dict],
262        celestial_points: List[dict]
263    ) -> List[AspectModel]:
264        """
265        Calculate all aspects within a single chart.
266
267        This method handles all aspect calculations including settings updates,
268        opposite pair filtering, and planet ID resolution for single charts.
269        Works with any chart type (natal, return, composite, etc.).
270
271        Returns:
272            List of all calculated AspectModel instances
273        """
274        active_points_list = get_active_points_list(subject, active_points)
275
276        # Update aspects settings with active aspects orbs
277        filtered_settings = AspectsFactory._update_aspect_settings(aspects_settings, active_aspects)
278
279        # Create a lookup dictionary for planet IDs to optimize performance
280        planet_id_lookup = {planet["name"]: planet["id"] for planet in celestial_points}
281
282        # Define opposite pairs that should be skipped for single chart aspects
283        opposite_pairs = {
284            ("Ascendant", "Descendant"),
285            ("Descendant", "Ascendant"),
286            ("Medium_Coeli", "Imum_Coeli"),
287            ("Imum_Coeli", "Medium_Coeli"),
288            ("True_Node", "True_South_Node"),
289            ("Mean_Node", "Mean_South_Node"),
290            ("True_South_Node", "True_Node"),
291            ("Mean_South_Node", "Mean_Node"),
292        }
293
294        all_aspects_list = []
295
296        for first in range(len(active_points_list)):
297            # Generate aspects list without repetitions (single chart - same chart)
298            for second in range(first + 1, len(active_points_list)):
299                # Skip predefined opposite pairs (AC/DC, MC/IC, North/South nodes)
300                first_name = active_points_list[first]["name"]
301                second_name = active_points_list[second]["name"]
302
303                if (first_name, second_name) in opposite_pairs:
304                    continue
305
306                aspect = get_aspect_from_two_points(
307                    filtered_settings,
308                    active_points_list[first]["abs_pos"],
309                    active_points_list[second]["abs_pos"]
310                )
311
312                if aspect["verdict"]:
313                    # Get planet IDs using lookup dictionary for better performance
314                    first_planet_id = planet_id_lookup.get(first_name, 0)
315                    second_planet_id = planet_id_lookup.get(second_name, 0)
316
317                    aspect_model = AspectModel(
318                        p1_name=first_name,
319                        p1_owner=subject.name,
320                        p1_abs_pos=active_points_list[first]["abs_pos"],
321                        p2_name=second_name,
322                        p2_owner=subject.name,
323                        p2_abs_pos=active_points_list[second]["abs_pos"],
324                        aspect=aspect["name"],
325                        orbit=aspect["orbit"],
326                        aspect_degrees=aspect["aspect_degrees"],
327                        diff=aspect["diff"],
328                        p1=first_planet_id,
329                        p2=second_planet_id,
330                    )
331                    all_aspects_list.append(aspect_model)
332
333        return all_aspects_list
334
335    @staticmethod
336    def _calculate_dual_chart_aspects(
337        first_subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
338        second_subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
339        active_points: List[AstrologicalPoint],
340        active_aspects: List[ActiveAspect],
341        aspects_settings: List[dict],
342        celestial_points: List[dict]
343    ) -> List[AspectModel]:
344        """
345        Calculate all aspects between two charts.
346
347        This method performs comprehensive aspect calculations between all active points
348        of both subjects, applying the specified orb settings and creating detailed
349        aspect models with planet IDs and positional information.
350        Works with any chart types (synastry, transits, comparisons, etc.).
351
352        Args:
353            first_subject: First astrological subject
354            second_subject: Second astrological subject
355            active_points: List of celestial points to include in calculations
356            active_aspects: List of aspect types with their orb settings
357            aspects_settings: Base aspect configuration settings
358            celestial_points: Celestial points configuration with IDs
359
360        Returns:
361            List[AspectModel]: Complete list of all calculated aspect instances
362        """
363        # Get active points lists for both subjects
364        first_active_points_list = get_active_points_list(first_subject, active_points)
365        second_active_points_list = get_active_points_list(second_subject, active_points)
366
367        # Create a lookup dictionary for planet IDs to optimize performance
368        planet_id_lookup = {planet["name"]: planet["id"] for planet in celestial_points}
369
370        # Update aspects settings with active aspects orbs
371        filtered_settings = AspectsFactory._update_aspect_settings(aspects_settings, active_aspects)
372
373        all_aspects_list = []
374        for first in range(len(first_active_points_list)):
375            # Generate aspects list between all points of first and second subjects
376            for second in range(len(second_active_points_list)):
377                aspect = get_aspect_from_two_points(
378                    filtered_settings,
379                    first_active_points_list[first]["abs_pos"],
380                    second_active_points_list[second]["abs_pos"],
381                )
382
383                if aspect["verdict"]:
384                    first_name = first_active_points_list[first]["name"]
385                    second_name = second_active_points_list[second]["name"]
386
387                    # Get planet IDs using lookup dictionary for better performance
388                    first_planet_id = planet_id_lookup.get(first_name, 0)
389                    second_planet_id = planet_id_lookup.get(second_name, 0)
390
391                    aspect_model = AspectModel(
392                        p1_name=first_name,
393                        p1_owner=first_subject.name,
394                        p1_abs_pos=first_active_points_list[first]["abs_pos"],
395                        p2_name=second_name,
396                        p2_owner=second_subject.name,
397                        p2_abs_pos=second_active_points_list[second]["abs_pos"],
398                        aspect=aspect["name"],
399                        orbit=aspect["orbit"],
400                        aspect_degrees=aspect["aspect_degrees"],
401                        diff=aspect["diff"],
402                        p1=first_planet_id,
403                        p2=second_planet_id,
404                    )
405                    all_aspects_list.append(aspect_model)
406
407        return all_aspects_list
408
409    @staticmethod
410    def _update_aspect_settings(
411        aspects_settings: List[dict],
412        active_aspects: List[ActiveAspect]
413    ) -> List[dict]:
414        """
415        Update aspects settings with active aspects orbs.
416
417        This is a common utility method used by both single chart and dual chart calculations.
418
419        Args:
420            aspects_settings: Base aspect settings
421            active_aspects: Active aspects with their orb configurations
422
423        Returns:
424            List of filtered and updated aspect settings
425        """
426        filtered_settings = []
427        for aspect_setting in aspects_settings:
428            for active_aspect in active_aspects:
429                if aspect_setting["name"] == active_aspect["name"]:
430                    aspect_setting = aspect_setting.copy()  # Don't modify original
431                    aspect_setting["orb"] = active_aspect["orb"]
432                    filtered_settings.append(aspect_setting)
433                    break
434        return filtered_settings
435
436    @staticmethod
437    def _filter_relevant_aspects(all_aspects: List[AspectModel], axes_orbit_settings: float) -> List[AspectModel]:
438        """
439        Filter aspects based on orb thresholds for axes and comprehensive criteria.
440
441        This method consolidates all filtering logic including axes checks and orb thresholds
442        for both single chart and dual chart aspects in a single comprehensive filtering method.
443
444        Args:
445            all_aspects: Complete list of calculated aspects
446            axes_orbit_settings: Orb threshold for axes aspects
447
448        Returns:
449            Filtered list of relevant aspects
450        """
451        logging.debug("Calculating relevant aspects by filtering orbs...")
452
453        relevant_aspects = []
454
455        for aspect in all_aspects:
456            # Check if aspect involves any of the chart axes and apply stricter orb limits
457            aspect_involves_axes = (aspect.p1_name in AXES_LIST or aspect.p2_name in AXES_LIST)
458
459            if aspect_involves_axes and abs(aspect.orbit) >= axes_orbit_settings:
460                continue
461
462            relevant_aspects.append(aspect)
463
464        return relevant_aspects
465
466    # Legacy methods for temporary backward compatibility
467    @staticmethod
468    def natal_aspects(
469        subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
470        *,
471        active_points: Optional[List[AstrologicalPoint]] = None,
472        active_aspects: Optional[List[ActiveAspect]] = None,
473    ) -> NatalAspectsModel:
474        """
475        Legacy method - use single_chart_aspects() instead.
476
477        ⚠️  DEPRECATION WARNING ⚠️
478        This method is deprecated. Use AspectsFactory.single_chart_aspects() instead.
479        """
480        return AspectsFactory.single_chart_aspects(subject, active_points=active_points, active_aspects=active_aspects)
481
482    @staticmethod
483    def synastry_aspects(
484        first_subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
485        second_subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
486        *,
487        active_points: Optional[List[AstrologicalPoint]] = None,
488        active_aspects: Optional[List[ActiveAspect]] = None,
489    ) -> SynastryAspectsModel:
490        """
491        Legacy method - use dual_chart_aspects() instead.
492
493        ⚠️  DEPRECATION WARNING ⚠️
494        This method is deprecated. Use AspectsFactory.dual_chart_aspects() instead.
495        """
496        return AspectsFactory.dual_chart_aspects(
497            first_subject, second_subject, active_points=active_points, active_aspects=active_aspects
498        )

 299class AstrologicalSubjectFactory:
 300    """
 301    Factory class for creating comprehensive astrological subjects.
 302
 303    This factory creates AstrologicalSubjectModel instances with complete astrological
 304    information including planetary positions, house cusps, aspects, lunar phases, and
 305    various specialized astrological points. It provides multiple class methods for
 306    different initialization scenarios and supports both online and offline calculation modes.
 307
 308    The factory handles complex astrological calculations using the Swiss Ephemeris library,
 309    supports multiple coordinate systems and house systems, and can automatically fetch
 310    location data from online sources.
 311
 312    Supported Astrological Points:
 313        - Traditional Planets: Sun through Pluto
 314        - Lunar Nodes: Mean and True North/South Nodes
 315        - Lilith Points: Mean and True Black Moon
 316        - Asteroids: Ceres, Pallas, Juno, Vesta
 317        - Centaurs: Chiron, Pholus
 318        - Trans-Neptunian Objects: Eris, Sedna, Haumea, Makemake, Ixion, Orcus, Quaoar
 319        - Fixed Stars: Regulus, Spica (extensible)
 320        - Arabic Parts: Pars Fortunae, Pars Spiritus, Pars Amoris, Pars Fidei
 321        - Special Points: Vertex, Anti-Vertex, Earth (for heliocentric charts)
 322        - House Cusps: All 12 houses with configurable house systems
 323        - Angles: Ascendant, Medium Coeli, Descendant, Imum Coeli
 324
 325    Supported Features:
 326        - Multiple zodiac systems (Tropical/Sidereal with various ayanamshas)
 327        - Multiple house systems (Placidus, Koch, Equal, Whole Sign, etc.)
 328        - Multiple coordinate perspectives (Geocentric, Heliocentric, Topocentric)
 329        - Automatic timezone and coordinate resolution via GeoNames API
 330        - Lunar phase calculations
 331        - Day/night chart detection for Arabic parts
 332        - Performance optimization through selective point calculation
 333        - Comprehensive error handling and validation
 334
 335    Class Methods:
 336        from_birth_data: Create subject from standard birth data (most flexible)
 337        from_iso_utc_time: Create subject from ISO UTC timestamp
 338        from_current_time: Create subject for current moment
 339
 340    Example:
 341        >>> # Create natal chart
 342        >>> subject = AstrologicalSubjectFactory.from_birth_data(
 343        ...     name="John Doe",
 344        ...     year=1990, month=6, day=15,
 345        ...     hour=14, minute=30,
 346        ...     city="Rome", nation="IT",
 347        ...     online=True
 348        ... )
 349        >>> print(f"Sun: {subject.sun.sign} {subject.sun.abs_pos}°")
 350        >>> print(f"Active points: {len(subject.active_points)}")
 351
 352        >>> # Create chart for current time
 353        >>> now_subject = AstrologicalSubjectFactory.from_current_time(
 354        ...     name="Current Moment",
 355        ...     city="London", nation="GB"
 356        ... )
 357
 358    Thread Safety:
 359        This factory is not thread-safe due to its use of the Swiss Ephemeris library
 360        which maintains global state. Use separate instances in multi-threaded applications
 361        or implement appropriate locking mechanisms.
 362    """
 363
 364    @classmethod
 365    def from_birth_data(
 366        cls,
 367        name: str = "Now",
 368        year: int = NOW.year,
 369        month: int = NOW.month,
 370        day: int = NOW.day,
 371        hour: int = NOW.hour,
 372        minute: int = NOW.minute,
 373        city: Optional[str] = None,
 374        nation: Optional[str] = None,
 375        lng: Optional[float] = None,
 376        lat: Optional[float] = None,
 377        tz_str: Optional[str] = None,
 378        geonames_username: Optional[str] = None,
 379        online: bool = True,
 380        zodiac_type: ZodiacType = DEFAULT_ZODIAC_TYPE,
 381        sidereal_mode: Optional[SiderealMode] = None,
 382        houses_system_identifier: HousesSystemIdentifier = DEFAULT_HOUSES_SYSTEM_IDENTIFIER,
 383        perspective_type: PerspectiveType = DEFAULT_PERSPECTIVE_TYPE,
 384        cache_expire_after_days: int = DEFAULT_GEONAMES_CACHE_EXPIRE_AFTER_DAYS,
 385        is_dst: Optional[bool] = None,
 386        altitude: Optional[float] = None,
 387        active_points: List[AstrologicalPoint] = DEFAULT_ACTIVE_POINTS,
 388        calculate_lunar_phase: bool = True,
 389        *,
 390        seconds: int = 0,
 391
 392    ) -> AstrologicalSubjectModel:
 393        """
 394        Create an astrological subject from standard birth or event data.
 395
 396        This is the most flexible and commonly used factory method. It creates a complete
 397        astrological subject with planetary positions, house cusps, and specialized points
 398        for a specific date, time, and location. Supports both online location resolution
 399        and offline calculation modes.
 400
 401        Args:
 402            name (str, optional): Name or identifier for the subject. Defaults to "Now".
 403            year (int, optional): Year of birth/event. Defaults to current year.
 404            month (int, optional): Month of birth/event (1-12). Defaults to current month.
 405            day (int, optional): Day of birth/event (1-31). Defaults to current day.
 406            hour (int, optional): Hour of birth/event (0-23). Defaults to current hour.
 407            minute (int, optional): Minute of birth/event (0-59). Defaults to current minute.
 408            seconds (int, optional): Seconds of birth/event (0-59). Defaults to 0.
 409            city (str, optional): City name for location lookup. Used with online=True.
 410                Defaults to None (Greenwich if not specified).
 411            nation (str, optional): ISO country code (e.g., 'US', 'GB', 'IT'). Used with
 412                online=True. Defaults to None ('GB' if not specified).
 413            lng (float, optional): Longitude in decimal degrees. East is positive, West
 414                is negative. If not provided and online=True, fetched from GeoNames.
 415            lat (float, optional): Latitude in decimal degrees. North is positive, South
 416                is negative. If not provided and online=True, fetched from GeoNames.
 417            tz_str (str, optional): IANA timezone identifier (e.g., 'Europe/London').
 418                If not provided and online=True, fetched from GeoNames.
 419            geonames_username (str, optional): Username for GeoNames API. Required for
 420                online location lookup. Get one free at geonames.org.
 421            online (bool, optional): Whether to fetch location data online. If False,
 422                lng, lat, and tz_str must be provided. Defaults to True.
 423            zodiac_type (ZodiacType, optional): Zodiac system - 'Tropic' or 'Sidereal'.
 424                Defaults to 'Tropic'.
 425            sidereal_mode (SiderealMode, optional): Sidereal calculation mode (e.g.,
 426                'FAGAN_BRADLEY', 'LAHIRI'). Only used with zodiac_type='Sidereal'.
 427            houses_system_identifier (HousesSystemIdentifier, optional): House system
 428                for cusp calculations (e.g., 'P'=Placidus, 'K'=Koch, 'E'=Equal).
 429                Defaults to 'P' (Placidus).
 430            perspective_type (PerspectiveType, optional): Calculation perspective:
 431                - 'Apparent Geocentric': Standard geocentric with light-time correction
 432                - 'True Geocentric': Geometric geocentric positions
 433                - 'Heliocentric': Sun-centered coordinates
 434                - 'Topocentric': Earth surface perspective (requires altitude)
 435                Defaults to 'Apparent Geocentric'.
 436            cache_expire_after_days (int, optional): Days to cache GeoNames data locally.
 437                Defaults to 30.
 438            is_dst (bool, optional): Daylight Saving Time flag for ambiguous times.
 439                If None, pytz attempts automatic detection. Set explicitly for
 440                times during DST transitions.
 441            altitude (float, optional): Altitude above sea level in meters. Used for
 442                topocentric calculations and atmospheric corrections. Defaults to None
 443                (sea level assumed).
 444            active_points (List[AstrologicalPoint], optional): List of astrological
 445                points to calculate. Omitting points can improve performance for
 446                specialized applications. Defaults to DEFAULT_ACTIVE_POINTS.
 447            calculate_lunar_phase (bool, optional): Whether to calculate lunar phase.
 448                Requires Sun and Moon in active_points. Defaults to True.
 449
 450        Returns:
 451            AstrologicalSubjectModel: Complete astrological subject with calculated
 452                positions, houses, and metadata. Access planetary positions via
 453                attributes like .sun, .moon, .mercury, etc.
 454
 455        Raises:
 456            KerykeionException:
 457                - If offline mode is used without required location data
 458                - If invalid zodiac/sidereal mode combinations are specified
 459                - If GeoNames data is missing or invalid
 460                - If timezone localization fails (ambiguous DST times)
 461
 462        Examples:
 463            >>> # Basic natal chart with online location lookup
 464            >>> chart = AstrologicalSubjectFactory.from_birth_data(
 465            ...     name="Jane Doe",
 466            ...     year=1985, month=3, day=21,
 467            ...     hour=15, minute=30,
 468            ...     city="Paris", nation="FR",
 469            ...     geonames_username="your_username"
 470            ... )
 471
 472            >>> # Offline calculation with manual coordinates
 473            >>> chart = AstrologicalSubjectFactory.from_birth_data(
 474            ...     name="John Smith",
 475            ...     year=1990, month=12, day=25,
 476            ...     hour=0, minute=0,
 477            ...     lng=-74.006, lat=40.7128, tz_str="America/New_York",
 478            ...     online=False
 479            ... )
 480
 481            >>> # Sidereal chart with specific points
 482            >>> chart = AstrologicalSubjectFactory.from_birth_data(
 483            ...     name="Vedic Chart",
 484            ...     year=2000, month=6, day=15, hour=12,
 485            ...     city="Mumbai", nation="IN",
 486            ...     zodiac_type="Sidereal",
 487            ...     sidereal_mode="LAHIRI",
 488            ...     active_points=["Sun", "Moon", "Mercury", "Venus", "Mars",
 489            ...                   "Jupiter", "Saturn", "Ascendant"]
 490            ... )
 491
 492        Note:
 493            - For high-precision calculations, consider providing seconds parameter
 494            - Use topocentric perspective for observer-specific calculations
 495            - Some Arabic parts automatically activate required base points
 496            - The method handles polar regions by adjusting extreme latitudes
 497            - Time zones are handled with full DST awareness via pytz
 498        """
 499        # Create a calculation data container
 500        calc_data = {}
 501
 502        # Basic identity
 503        calc_data["name"] = name
 504        calc_data["json_dir"] = str(Path.home())
 505
 506        # Create a deep copy of active points to avoid modifying the original list
 507        active_points = list(active_points)
 508
 509        calc_data["active_points"] = active_points
 510
 511        # Initialize configuration
 512        config = ChartConfiguration(
 513            zodiac_type=zodiac_type,
 514            sidereal_mode=sidereal_mode,
 515            houses_system_identifier=houses_system_identifier,
 516            perspective_type=perspective_type,
 517        )
 518        config.validate()
 519
 520        # Add configuration data to calculation data
 521        calc_data["zodiac_type"] = config.zodiac_type
 522        calc_data["sidereal_mode"] = config.sidereal_mode
 523        calc_data["houses_system_identifier"] = config.houses_system_identifier
 524        calc_data["perspective_type"] = config.perspective_type
 525
 526        # Set up geonames username if needed
 527        if geonames_username is None and online and (not lat or not lng or not tz_str):
 528            logging.warning(GEONAMES_DEFAULT_USERNAME_WARNING)
 529            geonames_username = DEFAULT_GEONAMES_USERNAME
 530
 531        # Initialize location data
 532        location = LocationData(
 533            city=city or "Greenwich",
 534            nation=nation or "GB",
 535            lat=lat if lat is not None else 51.5074,
 536            lng=lng if lng is not None else 0.0,
 537            tz_str=tz_str or "Etc/GMT",
 538            altitude=altitude
 539        )
 540
 541        # If offline mode is requested but required data is missing, raise error
 542        if not online and (not tz_str or lat is None or lng is None):
 543            raise KerykeionException(
 544                "For offline mode, you must provide timezone (tz_str) and coordinates (lat, lng)"
 545            )
 546
 547        # Fetch location data if needed
 548        if online and (not tz_str or lat is None or lng is None):
 549            location.fetch_from_geonames(
 550                username=geonames_username or DEFAULT_GEONAMES_USERNAME,
 551                cache_expire_after_days=cache_expire_after_days
 552            )
 553
 554        # Prepare location for calculations
 555        location.prepare_for_calculation()
 556
 557        # Add location data to calculation data
 558        calc_data["city"] = location.city
 559        calc_data["nation"] = location.nation
 560        calc_data["lat"] = location.lat
 561        calc_data["lng"] = location.lng
 562        calc_data["tz_str"] = location.tz_str
 563        calc_data["altitude"] = location.altitude
 564
 565        # Store calculation parameters
 566        calc_data["year"] = year
 567        calc_data["month"] = month
 568        calc_data["day"] = day
 569        calc_data["hour"] = hour
 570        calc_data["minute"] = minute
 571        calc_data["seconds"] = seconds
 572        calc_data["is_dst"] = is_dst
 573
 574        # Calculate time conversions
 575        cls._calculate_time_conversions(calc_data, location)
 576
 577        # Initialize Swiss Ephemeris and calculate houses and planets
 578        cls._setup_ephemeris(calc_data, config)
 579        cls._calculate_houses(calc_data, calc_data["active_points"])
 580        cls._calculate_planets(calc_data, calc_data["active_points"])
 581        cls._calculate_day_of_week(calc_data)
 582
 583        # Calculate lunar phase (optional - only if requested and Sun and Moon are available)
 584        if calculate_lunar_phase and "moon" in calc_data and "sun" in calc_data:
 585            calc_data["lunar_phase"] = calculate_moon_phase(
 586                calc_data["moon"].abs_pos,
 587                calc_data["sun"].abs_pos
 588            )
 589
 590        # Create and return the AstrologicalSubjectModel
 591        return AstrologicalSubjectModel(**calc_data)
 592
 593    @classmethod
 594    def from_iso_utc_time(
 595        cls,
 596        name: str,
 597        iso_utc_time: str,
 598        city: str = "Greenwich",
 599        nation: str = "GB",
 600        tz_str: str = "Etc/GMT",
 601        online: bool = True,
 602        lng: float = 0.0,
 603        lat: float = 51.5074,
 604        geonames_username: str = DEFAULT_GEONAMES_USERNAME,
 605        zodiac_type: ZodiacType = DEFAULT_ZODIAC_TYPE,
 606        sidereal_mode: Optional[SiderealMode] = None,
 607        houses_system_identifier: HousesSystemIdentifier = DEFAULT_HOUSES_SYSTEM_IDENTIFIER,
 608        perspective_type: PerspectiveType = DEFAULT_PERSPECTIVE_TYPE,
 609        altitude: Optional[float] = None,
 610        active_points: List[AstrologicalPoint] = DEFAULT_ACTIVE_POINTS,
 611        calculate_lunar_phase: bool = True
 612    ) -> AstrologicalSubjectModel:
 613        """
 614        Create an astrological subject from an ISO formatted UTC timestamp.
 615
 616        This method is ideal for creating astrological subjects from standardized
 617        time formats, such as those stored in databases or received from APIs.
 618        It automatically handles timezone conversion from UTC to the specified
 619        local timezone.
 620
 621        Args:
 622            name (str): Name or identifier for the subject.
 623            iso_utc_time (str): ISO 8601 formatted UTC timestamp. Supported formats:
 624                - "2023-06-15T14:30:00Z" (with Z suffix)
 625                - "2023-06-15T14:30:00+00:00" (with UTC offset)
 626                - "2023-06-15T14:30:00.123Z" (with milliseconds)
 627            city (str, optional): City name for location. Defaults to "Greenwich".
 628            nation (str, optional): ISO country code. Defaults to "GB".
 629            tz_str (str, optional): IANA timezone identifier for result conversion.
 630                The ISO time is assumed to be in UTC and will be converted to this
 631                timezone. Defaults to "Etc/GMT".
 632            online (bool, optional): Whether to fetch coordinates online. If True,
 633                coordinates are fetched via GeoNames API. Defaults to True.
 634            lng (float, optional): Longitude in decimal degrees. Used when online=False
 635                or as fallback. Defaults to 0.0 (Greenwich).
 636            lat (float, optional): Latitude in decimal degrees. Used when online=False
 637                or as fallback. Defaults to 51.5074 (Greenwich).
 638            geonames_username (str, optional): GeoNames API username. Required when
 639                online=True. Defaults to DEFAULT_GEONAMES_USERNAME.
 640            zodiac_type (ZodiacType, optional): Zodiac system. Defaults to 'Tropic'.
 641            sidereal_mode (SiderealMode, optional): Sidereal mode when zodiac_type
 642                is 'Sidereal'. Defaults to None.
 643            houses_system_identifier (HousesSystemIdentifier, optional): House system.
 644                Defaults to 'P' (Placidus).
 645            perspective_type (PerspectiveType, optional): Calculation perspective.
 646                Defaults to 'Apparent Geocentric'.
 647            altitude (float, optional): Altitude in meters for topocentric calculations.
 648                Defaults to None (sea level).
 649            active_points (List[AstrologicalPoint], optional): Points to calculate.
 650                Defaults to DEFAULT_ACTIVE_POINTS.
 651            calculate_lunar_phase (bool, optional): Whether to calculate lunar phase.
 652                Defaults to True.
 653
 654        Returns:
 655            AstrologicalSubjectModel: Astrological subject with positions calculated
 656                for the specified UTC time converted to local timezone.
 657
 658        Raises:
 659            ValueError: If the ISO timestamp format is invalid or cannot be parsed.
 660            KerykeionException: If location data cannot be fetched or is invalid.
 661
 662        Examples:
 663            >>> # From API timestamp with online location lookup
 664            >>> subject = AstrologicalSubjectFactory.from_iso_utc_time(
 665            ...     name="Event Chart",
 666            ...     iso_utc_time="2023-12-25T12:00:00Z",
 667            ...     city="Tokyo", nation="JP",
 668            ...     tz_str="Asia/Tokyo",
 669            ...     geonames_username="your_username"
 670            ... )
 671
 672            >>> # From database timestamp with manual coordinates
 673            >>> subject = AstrologicalSubjectFactory.from_iso_utc_time(
 674            ...     name="Historical Event",
 675            ...     iso_utc_time="1969-07-20T20:17:00Z",
 676            ...     lng=-95.0969, lat=37.4419,  # Houston
 677            ...     tz_str="America/Chicago",
 678            ...     online=False
 679            ... )
 680
 681        Note:
 682            - The method assumes the input timestamp is in UTC
 683            - Local time conversion respects DST rules for the target timezone
 684            - Milliseconds in the timestamp are supported but truncated to seconds
 685            - When online=True, the city/nation parameters override lng/lat
 686        """
 687        # Parse the ISO time
 688        dt = datetime.fromisoformat(iso_utc_time.replace('Z', '+00:00'))
 689
 690        # Get location data if online mode is enabled
 691        if online:
 692            if geonames_username == DEFAULT_GEONAMES_USERNAME:
 693                logging.warning(GEONAMES_DEFAULT_USERNAME_WARNING)
 694
 695            geonames = FetchGeonames(
 696                city,
 697                nation,
 698                username=geonames_username,
 699            )
 700
 701            city_data = geonames.get_serialized_data()
 702            lng = float(city_data["lng"])
 703            lat = float(city_data["lat"])
 704
 705        # Convert UTC to local time
 706        local_time = pytz.timezone(tz_str)
 707        local_datetime = dt.astimezone(local_time)
 708
 709        # Create the subject with local time
 710        return cls.from_birth_data(
 711            name=name,
 712            year=local_datetime.year,
 713            month=local_datetime.month,
 714            day=local_datetime.day,
 715            hour=local_datetime.hour,
 716            minute=local_datetime.minute,
 717            seconds=local_datetime.second,
 718            city=city,
 719            nation=nation,
 720            lng=lng,
 721            lat=lat,
 722            tz_str=tz_str,
 723            online=False,  # Already fetched data if needed
 724            geonames_username=geonames_username,
 725            zodiac_type=zodiac_type,
 726            sidereal_mode=sidereal_mode,
 727            houses_system_identifier=houses_system_identifier,
 728            perspective_type=perspective_type,
 729            altitude=altitude,
 730            active_points=active_points,
 731            calculate_lunar_phase=calculate_lunar_phase
 732        )
 733
 734    @classmethod
 735    def from_current_time(
 736        cls,
 737        name: str = "Now",
 738        city: Optional[str] = None,
 739        nation: Optional[str] = None,
 740        lng: Optional[float] = None,
 741        lat: Optional[float] = None,
 742        tz_str: Optional[str] = None,
 743        geonames_username: Optional[str] = None,
 744        online: bool = True,
 745        zodiac_type: ZodiacType = DEFAULT_ZODIAC_TYPE,
 746        sidereal_mode: Optional[SiderealMode] = None,
 747        houses_system_identifier: HousesSystemIdentifier = DEFAULT_HOUSES_SYSTEM_IDENTIFIER,
 748        perspective_type: PerspectiveType = DEFAULT_PERSPECTIVE_TYPE,
 749        active_points: List[AstrologicalPoint] = DEFAULT_ACTIVE_POINTS,
 750        calculate_lunar_phase: bool = True
 751    ) -> AstrologicalSubjectModel:
 752        """
 753        Create an astrological subject for the current moment in time.
 754
 755        This convenience method creates a "now" chart, capturing the current
 756        astrological conditions at the moment of execution. Useful for horary
 757        astrology, electional astrology, or real-time astrological monitoring.
 758
 759        Args:
 760            name (str, optional): Name for the current moment chart.
 761                Defaults to "Now".
 762            city (str, optional): City name for location lookup. If not provided
 763                and online=True, defaults to Greenwich.
 764            nation (str, optional): ISO country code. If not provided and
 765                online=True, defaults to 'GB'.
 766            lng (float, optional): Longitude in decimal degrees. If not provided
 767                and online=True, fetched from GeoNames API.
 768            lat (float, optional): Latitude in decimal degrees. If not provided
 769                and online=True, fetched from GeoNames API.
 770            tz_str (str, optional): IANA timezone identifier. If not provided
 771                and online=True, fetched from GeoNames API.
 772            geonames_username (str, optional): GeoNames API username for location
 773                lookup. Required when online=True and location is not fully specified.
 774            online (bool, optional): Whether to fetch location data online.
 775                Defaults to True.
 776            zodiac_type (ZodiacType, optional): Zodiac system to use.
 777                Defaults to 'Tropic'.
 778            sidereal_mode (SiderealMode, optional): Sidereal calculation mode.
 779                Only used when zodiac_type is 'Sidereal'. Defaults to None.
 780            houses_system_identifier (HousesSystemIdentifier, optional): House
 781                system for calculations. Defaults to 'P' (Placidus).
 782            perspective_type (PerspectiveType, optional): Calculation perspective.
 783                Defaults to 'Apparent Geocentric'.
 784            active_points (List[AstrologicalPoint], optional): Astrological points
 785                to calculate. Defaults to DEFAULT_ACTIVE_POINTS.
 786            calculate_lunar_phase (bool, optional): Whether to calculate lunar phase.
 787                Defaults to True.
 788
 789        Returns:
 790            AstrologicalSubjectModel: Astrological subject representing current
 791                astrological conditions at the specified or default location.
 792
 793        Raises:
 794            KerykeionException: If online location lookup fails or if offline mode
 795                is used without sufficient location data.
 796
 797        Examples:
 798            >>> # Current moment for your location
 799            >>> now_chart = AstrologicalSubjectFactory.from_current_time(
 800            ...     name="Current Transits",
 801            ...     city="New York", nation="US",
 802            ...     geonames_username="your_username"
 803            ... )
 804
 805            >>> # Horary chart with specific coordinates
 806            >>> horary = AstrologicalSubjectFactory.from_current_time(
 807            ...     name="Horary Question",
 808            ...     lng=-0.1278, lat=51.5074,  # London
 809            ...     tz_str="Europe/London",
 810            ...     online=False
 811            ... )
 812
 813            >>> # Current sidereal positions
 814            >>> sidereal_now = AstrologicalSubjectFactory.from_current_time(
 815            ...     name="Sidereal Now",
 816            ...     city="Mumbai", nation="IN",
 817            ...     zodiac_type="Sidereal",
 818            ...     sidereal_mode="LAHIRI"
 819            ... )
 820
 821        Note:
 822            - The exact time is captured at method execution, including seconds
 823            - For horary astrology, consider the moment of understanding the question
 824            - System clock accuracy affects precision; ensure accurate system time
 825            - Time zone detection is automatic when using online location lookup
 826        """
 827        now = datetime.now()
 828
 829        return cls.from_birth_data(
 830            name=name,
 831            year=now.year,
 832            month=now.month,
 833            day=now.day,
 834            hour=now.hour,
 835            minute=now.minute,
 836            seconds=now.second,
 837            city=city,
 838            nation=nation,
 839            lng=lng,
 840            lat=lat,
 841            tz_str=tz_str,
 842            geonames_username=geonames_username,
 843            online=online,
 844            zodiac_type=zodiac_type,
 845            sidereal_mode=sidereal_mode,
 846            houses_system_identifier=houses_system_identifier,
 847            perspective_type=perspective_type,
 848            active_points=active_points,
 849            calculate_lunar_phase=calculate_lunar_phase
 850        )
 851
 852    @classmethod
 853    def _calculate_time_conversions(cls, data: Dict[str, Any], location: LocationData) -> None:
 854        """
 855        Calculate time conversions between local time, UTC, and Julian Day Number.
 856
 857        Handles timezone-aware conversion from local civil time to UTC and astronomical
 858        Julian Day Number, including proper DST handling and timezone localization.
 859
 860        Args:
 861            data (Dict[str, Any]): Calculation data dictionary containing time components
 862                (year, month, day, hour, minute, seconds) and optional DST flag.
 863            location (LocationData): Location data containing timezone information.
 864
 865        Raises:
 866            KerykeionException: If DST ambiguity occurs during timezone transitions
 867                and is_dst parameter is not explicitly set to resolve the ambiguity.
 868
 869        Side Effects:
 870            Updates data dictionary with:
 871            - iso_formatted_utc_datetime: ISO 8601 UTC timestamp
 872            - iso_formatted_local_datetime: ISO 8601 local timestamp
 873            - julian_day: Julian Day Number for astronomical calculations
 874
 875        Note:
 876            During DST transitions, times may be ambiguous (fall back) or non-existent
 877            (spring forward). The method raises an exception for ambiguous times unless
 878            the is_dst parameter is explicitly set to True or False.
 879        """
 880        # Convert local time to UTC
 881        local_timezone = pytz.timezone(location.tz_str)
 882        naive_datetime = datetime(
 883            data["year"], data["month"], data["day"],
 884            data["hour"], data["minute"], data["seconds"]
 885        )
 886
 887        try:
 888            local_datetime = local_timezone.localize(naive_datetime, is_dst=data.get("is_dst"))
 889        except pytz.exceptions.AmbiguousTimeError:
 890            raise KerykeionException(
 891                "Ambiguous time error! The time falls during a DST transition. "
 892                "Please specify is_dst=True or is_dst=False to clarify."
 893            )
 894
 895        # Store formatted times
 896        utc_datetime = local_datetime.astimezone(pytz.utc)
 897        data["iso_formatted_utc_datetime"] = utc_datetime.isoformat()
 898        data["iso_formatted_local_datetime"] = local_datetime.isoformat()
 899
 900        # Calculate Julian day
 901        data["julian_day"] = datetime_to_julian(utc_datetime)
 902
 903    @classmethod
 904    def _setup_ephemeris(cls, data: Dict[str, Any], config: ChartConfiguration) -> None:
 905        """
 906        Configure Swiss Ephemeris with appropriate calculation flags and settings.
 907
 908        Sets up the Swiss Ephemeris library with the correct ephemeris data path,
 909        calculation flags for the specified perspective type, and sidereal mode
 910        configuration if applicable.
 911
 912        Args:
 913            data (Dict[str, Any]): Calculation data dictionary to store configuration.
 914            config (ChartConfiguration): Validated chart configuration settings.
 915
 916        Side Effects:
 917            - Sets Swiss Ephemeris data path to bundled ephemeris files
 918            - Configures calculation flags (SWIEPH, SPEED, perspective flags)
 919            - Sets sidereal mode for sidereal zodiac calculations
 920            - Sets topocentric observer coordinates for topocentric perspective
 921            - Updates data dictionary with houses_system_name and _iflag
 922
 923        Calculation Flags Set:
 924            - FLG_SWIEPH: Use Swiss Ephemeris data files
 925            - FLG_SPEED: Calculate planetary velocities
 926            - FLG_TRUEPOS: True geometric positions (True Geocentric)
 927            - FLG_HELCTR: Heliocentric coordinates (Heliocentric perspective)
 928            - FLG_TOPOCTR: Topocentric coordinates (Topocentric perspective)
 929            - FLG_SIDEREAL: Sidereal calculations (Sidereal zodiac)
 930
 931        Note:
 932            The method assumes the Swiss Ephemeris data files are located in the
 933            'sweph' subdirectory relative to this module. For topocentric calculations,
 934            observer coordinates must be set via longitude, latitude, and altitude.
 935        """
 936        # Set ephemeris path
 937        swe.set_ephe_path(str(Path(__file__).parent.absolute() / "sweph"))
 938
 939        # Base flags
 940        iflag = swe.FLG_SWIEPH + swe.FLG_SPEED
 941
 942        # Add perspective flags
 943        if config.perspective_type == "True Geocentric":
 944            iflag += swe.FLG_TRUEPOS
 945        elif config.perspective_type == "Heliocentric":
 946            iflag += swe.FLG_HELCTR
 947        elif config.perspective_type == "Topocentric":
 948            iflag += swe.FLG_TOPOCTR
 949            # Set topocentric coordinates
 950            swe.set_topo(data["lng"], data["lat"], data["altitude"] or 0)
 951
 952        # Add sidereal flag if needed
 953        if config.zodiac_type == "Sidereal":
 954            iflag += swe.FLG_SIDEREAL
 955            # Set sidereal mode
 956            mode = f"SIDM_{config.sidereal_mode}"
 957            swe.set_sid_mode(getattr(swe, mode))
 958            logging.debug(f"Using sidereal mode: {mode}")
 959
 960        # Save house system name and iflag for later use
 961        data["houses_system_name"] = swe.house_name(
 962            config.houses_system_identifier.encode('ascii')
 963        )
 964        data["_iflag"] = iflag
 965
 966    @classmethod
 967    def _calculate_houses(cls, data: Dict[str, Any], active_points: Optional[List[AstrologicalPoint]]) -> None:
 968        """
 969        Calculate house cusps and angular points (Ascendant, MC, etc.).
 970
 971        Computes the 12 house cusps using the specified house system and calculates
 972        the four main angles of the chart. Only calculates angular points that are
 973        included in the active_points list for performance optimization.
 974
 975        Args:
 976            data (Dict[str, Any]): Calculation data dictionary containing configuration
 977                and location information. Updated with calculated house and angle data.
 978            active_points (Optional[List[AstrologicalPoint]]): List of points to calculate.
 979                If None, all points are calculated. Angular points not in this list
 980                are skipped for performance.
 981
 982        Side Effects:
 983            Updates data dictionary with:
 984            - House cusp objects: first_house through twelfth_house
 985            - Angular points: ascendant, medium_coeli, descendant, imum_coeli
 986            - houses_names_list: List of all house names
 987            - _houses_degree_ut: Raw house cusp degrees for internal use
 988
 989        House Systems Supported:
 990            All systems supported by Swiss Ephemeris including Placidus, Koch,
 991            Equal House, Whole Sign, Regiomontanus, Campanus, Topocentric, etc.
 992
 993        Angular Points Calculated:
 994            - Ascendant: Eastern horizon point (1st house cusp)
 995            - Medium Coeli (Midheaven): Southern meridian point (10th house cusp)
 996            - Descendant: Western horizon point (opposite Ascendant)
 997            - Imum Coeli: Northern meridian point (opposite Medium Coeli)
 998
 999        Note:
1000            House calculations respect the zodiac type (Tropical/Sidereal) and use
1001            the appropriate Swiss Ephemeris function. Angular points include house
1002            position and retrograde status (always False for angles).
1003        """
1004        # Skip calculation if point is not in active_points
1005        def should_calculate(point: AstrologicalPoint) -> bool:
1006            return not active_points or point in active_points
1007        # Track which axial cusps are actually calculated
1008        calculated_axial_cusps = []
1009
1010        # Calculate houses based on zodiac type
1011        if data["zodiac_type"] == "Sidereal":
1012            cusps, ascmc = swe.houses_ex(
1013                tjdut=data["julian_day"],
1014                lat=data["lat"],
1015                lon=data["lng"],
1016                hsys=str.encode(data["houses_system_identifier"]),
1017                flags=swe.FLG_SIDEREAL
1018            )
1019        else:  # Tropical zodiac
1020            cusps, ascmc = swe.houses(
1021                tjdut=data["julian_day"],
1022                lat=data["lat"],
1023                lon=data["lng"],
1024                hsys=str.encode(data["houses_system_identifier"])
1025            )
1026
1027        # Store house degrees
1028        data["_houses_degree_ut"] = cusps
1029
1030        # Create house objects
1031        point_type: PointType = "House"
1032        data["first_house"] = get_kerykeion_point_from_degree(cusps[0], "First_House", point_type=point_type)
1033        data["second_house"] = get_kerykeion_point_from_degree(cusps[1], "Second_House", point_type=point_type)
1034        data["third_house"] = get_kerykeion_point_from_degree(cusps[2], "Third_House", point_type=point_type)
1035        data["fourth_house"] = get_kerykeion_point_from_degree(cusps[3], "Fourth_House", point_type=point_type)
1036        data["fifth_house"] = get_kerykeion_point_from_degree(cusps[4], "Fifth_House", point_type=point_type)
1037        data["sixth_house"] = get_kerykeion_point_from_degree(cusps[5], "Sixth_House", point_type=point_type)
1038        data["seventh_house"] = get_kerykeion_point_from_degree(cusps[6], "Seventh_House", point_type=point_type)
1039        data["eighth_house"] = get_kerykeion_point_from_degree(cusps[7], "Eighth_House", point_type=point_type)
1040        data["ninth_house"] = get_kerykeion_point_from_degree(cusps[8], "Ninth_House", point_type=point_type)
1041        data["tenth_house"] = get_kerykeion_point_from_degree(cusps[9], "Tenth_House", point_type=point_type)
1042        data["eleventh_house"] = get_kerykeion_point_from_degree(cusps[10], "Eleventh_House", point_type=point_type)
1043        data["twelfth_house"] = get_kerykeion_point_from_degree(cusps[11], "Twelfth_House", point_type=point_type)
1044
1045        # Store house names
1046        data["houses_names_list"] = list(get_args(Houses))
1047
1048        # Calculate axis points
1049        point_type = "AstrologicalPoint"
1050
1051        # Calculate Ascendant if needed
1052        if should_calculate("Ascendant"):
1053            data["ascendant"] = get_kerykeion_point_from_degree(ascmc[0], "Ascendant", point_type=point_type)
1054            data["ascendant"].house = get_planet_house(data["ascendant"].abs_pos, data["_houses_degree_ut"])
1055            data["ascendant"].retrograde = False
1056            calculated_axial_cusps.append("Ascendant")
1057
1058        # Calculate Medium Coeli if needed
1059        if should_calculate("Medium_Coeli"):
1060            data["medium_coeli"] = get_kerykeion_point_from_degree(ascmc[1], "Medium_Coeli", point_type=point_type)
1061            data["medium_coeli"].house = get_planet_house(data["medium_coeli"].abs_pos, data["_houses_degree_ut"])
1062            data["medium_coeli"].retrograde = False
1063            calculated_axial_cusps.append("Medium_Coeli")
1064
1065        # Calculate Descendant if needed
1066        if should_calculate("Descendant"):
1067            dsc_deg = math.fmod(ascmc[0] + 180, 360)
1068            data["descendant"] = get_kerykeion_point_from_degree(dsc_deg, "Descendant", point_type=point_type)
1069            data["descendant"].house = get_planet_house(data["descendant"].abs_pos, data["_houses_degree_ut"])
1070            data["descendant"].retrograde = False
1071            calculated_axial_cusps.append("Descendant")
1072
1073        # Calculate Imum Coeli if needed
1074        if should_calculate("Imum_Coeli"):
1075            ic_deg = math.fmod(ascmc[1] + 180, 360)
1076            data["imum_coeli"] = get_kerykeion_point_from_degree(ic_deg, "Imum_Coeli", point_type=point_type)
1077            data["imum_coeli"].house = get_planet_house(data["imum_coeli"].abs_pos, data["_houses_degree_ut"])
1078            data["imum_coeli"].retrograde = False
1079            calculated_axial_cusps.append("Imum_Coeli")
1080
1081    @classmethod
1082    def _calculate_single_planet(
1083        cls,
1084        data: Dict[str, Any],
1085        planet_name: AstrologicalPoint,
1086        planet_id: int,
1087        julian_day: float,
1088        iflag: int,
1089        houses_degree_ut: List[float],
1090        point_type: PointType,
1091        calculated_planets: List[str],
1092        active_points: List[AstrologicalPoint]
1093    ) -> None:
1094        """
1095        Calculate a single celestial body's position with comprehensive error handling.
1096
1097        Computes the position of a single planet, asteroid, or other celestial object
1098        using Swiss Ephemeris, creates a Kerykeion point object, determines house
1099        position, and assesses retrograde status. Handles calculation errors gracefully
1100        by logging and removing failed points from the active list.
1101
1102        Args:
1103            data (Dict[str, Any]): Main calculation data dictionary to store results.
1104            planet_name (AstrologicalPoint): Name identifier for the celestial body.
1105            planet_id (int): Swiss Ephemeris numerical identifier for the object.
1106            julian_day (float): Julian Day Number for the calculation moment.
1107            iflag (int): Swiss Ephemeris calculation flags (perspective, zodiac, etc.).
1108            houses_degree_ut (List[float]): House cusp degrees for house determination.
1109            point_type (PointType): Classification of the point type for the object.
1110            calculated_planets (List[str]): Running list of successfully calculated objects.
1111            active_points (List[AstrologicalPoint]): Active points list (modified on error).
1112
1113        Side Effects:
1114            - Adds calculated object to data dictionary using lowercase planet_name as key
1115            - Appends planet_name to calculated_planets list on success
1116            - Removes planet_name from active_points list on calculation failure
1117            - Logs error messages for calculation failures
1118
1119        Calculated Properties:
1120            - Zodiacal position (longitude) in degrees
1121            - House position based on house cusp positions
1122            - Retrograde status based on velocity (negative = retrograde)
1123            - Sign, degree, and minute components
1124
1125        Error Handling:
1126            If Swiss Ephemeris calculation fails (e.g., for distant asteroids outside
1127            ephemeris range), the method logs the error and removes the object from
1128            active_points to prevent cascade failures.
1129
1130        Note:
1131            The method uses the Swiss Ephemeris calc_ut function which returns position
1132            and velocity data. Retrograde determination is based on the velocity
1133            component being negative (element index 3).
1134        """
1135        try:
1136            # Calculate planet position using Swiss Ephemeris
1137            planet_calc = swe.calc_ut(julian_day, planet_id, iflag)[0]
1138
1139            # Create Kerykeion point from degree
1140            data[planet_name.lower()] = get_kerykeion_point_from_degree(
1141                planet_calc[0], planet_name, point_type=point_type
1142            )
1143
1144            # Calculate house position
1145            data[planet_name.lower()].house = get_planet_house(planet_calc[0], houses_degree_ut)
1146
1147            # Determine if planet is retrograde
1148            data[planet_name.lower()].retrograde = planet_calc[3] < 0
1149
1150            # Track calculated planet
1151            calculated_planets.append(planet_name)
1152
1153        except Exception as e:
1154            logging.error(f"Error calculating {planet_name}: {e}")
1155            if planet_name in active_points:
1156                active_points.remove(planet_name)
1157
1158    @classmethod
1159    def _calculate_planets(cls, data: Dict[str, Any], active_points: List[AstrologicalPoint]) -> None:
1160        """
1161        Calculate positions for all requested celestial bodies and special points.
1162
1163        This comprehensive method calculates positions for a wide range of astrological
1164        points including traditional planets, lunar nodes, asteroids, trans-Neptunian
1165        objects, fixed stars, Arabic parts, and specialized points like Vertex.
1166
1167        The calculation is performed selectively based on the active_points list for
1168        performance optimization. Some Arabic parts automatically activate their
1169        prerequisite points if needed.
1170
1171        Args:
1172            data (Dict[str, Any]): Main calculation data dictionary. Updated with all
1173                calculated planetary positions and related metadata.
1174            active_points (List[AstrologicalPoint]): Mutable list of points to calculate.
1175                Modified during execution to remove failed calculations and add
1176                automatically required points for Arabic parts.
1177
1178        Celestial Bodies Calculated:
1179            Traditional Planets:
1180                - Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn
1181                - Uranus, Neptune, Pluto
1182
1183            Lunar Nodes:
1184                - Mean Node, True Node (North nodes)
1185                - Mean South Node, True South Node (calculated as opposites)
1186
1187            Lilith Points:
1188                - Mean Lilith (Mean Black Moon Lilith)
1189                - True Lilith (Osculating Black Moon Lilith)
1190
1191            Asteroids:
1192                - Ceres, Pallas, Juno, Vesta (main belt asteroids)
1193
1194            Centaurs:
1195                - Chiron, Pholus
1196
1197            Trans-Neptunian Objects:
1198                - Eris, Sedna, Haumea, Makemake
1199                - Ixion, Orcus, Quaoar
1200
1201            Fixed Stars:
1202                - Regulus, Spica (examples, extensible)
1203
1204            Arabic Parts (Lots):
1205                - Pars Fortunae (Part of Fortune)
1206                - Pars Spiritus (Part of Spirit)
1207                - Pars Amoris (Part of Love/Eros)
1208                - Pars Fidei (Part of Faith)
1209
1210            Special Points:
1211                - Earth (for heliocentric perspectives)
1212                - Vertex and Anti-Vertex
1213
1214        Side Effects:
1215            - Updates data dictionary with all calculated positions
1216            - Modifies active_points list by removing failed calculations
1217            - Adds prerequisite points for Arabic parts calculations
1218            - Updates data["active_points"] with successfully calculated objects
1219
1220        Error Handling:
1221            Individual calculation failures (e.g., asteroids outside ephemeris range)
1222            are handled gracefully with logging and removal from active_points.
1223            This prevents cascade failures while maintaining calculation integrity.
1224
1225        Arabic Parts Logic:
1226            - Day/night birth detection based on Sun's house position
1227            - Automatic activation of required base points (Sun, Moon, Ascendant, etc.)
1228            - Classical formulae with day/night variations where applicable
1229            - All parts marked as non-retrograde (conceptual points)
1230
1231        Performance Notes:
1232            - Only points in active_points are calculated (selective computation)
1233            - Failed calculations are removed to prevent repeated attempts
1234            - Some expensive calculations (like distant TNOs) may timeout
1235            - Fixed stars use different calculation methods than planets
1236
1237        Note:
1238            The method maintains a running list of successfully calculated planets
1239            and updates the active_points list to reflect actual availability.
1240            This ensures that dependent calculations and aspects only use valid data.
1241        """
1242        # Skip calculation if point is not in active_points
1243        def should_calculate(point: AstrologicalPoint) -> bool:
1244            return not active_points or point in active_points
1245
1246        point_type: PointType = "AstrologicalPoint"
1247        julian_day = data["julian_day"]
1248        iflag = data["_iflag"]
1249        houses_degree_ut = data["_houses_degree_ut"]
1250
1251        # Track which planets are actually calculated
1252        calculated_planets = []
1253
1254        # ==================
1255        # MAIN PLANETS
1256        # ==================
1257
1258        # Calculate Sun
1259        if should_calculate("Sun"):
1260            cls._calculate_single_planet(data, "Sun", 0, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1261
1262        # Calculate Moon
1263        if should_calculate("Moon"):
1264            cls._calculate_single_planet(data, "Moon", 1, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1265
1266        # Calculate Mercury
1267        if should_calculate("Mercury"):
1268            cls._calculate_single_planet(data, "Mercury", 2, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1269
1270        # Calculate Venus
1271        if should_calculate("Venus"):
1272            cls._calculate_single_planet(data, "Venus", 3, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1273
1274        # Calculate Mars
1275        if should_calculate("Mars"):
1276            cls._calculate_single_planet(data, "Mars", 4, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1277
1278        # Calculate Jupiter
1279        if should_calculate("Jupiter"):
1280            cls._calculate_single_planet(data, "Jupiter", 5, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1281
1282        # Calculate Saturn
1283        if should_calculate("Saturn"):
1284            cls._calculate_single_planet(data, "Saturn", 6, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1285
1286        # Calculate Uranus
1287        if should_calculate("Uranus"):
1288            cls._calculate_single_planet(data, "Uranus", 7, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1289
1290        # Calculate Neptune
1291        if should_calculate("Neptune"):
1292            cls._calculate_single_planet(data, "Neptune", 8, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1293
1294        # Calculate Pluto
1295        if should_calculate("Pluto"):
1296            cls._calculate_single_planet(data, "Pluto", 9, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1297
1298        # ==================
1299        # LUNAR NODES
1300        # ==================
1301
1302        # Calculate Mean Lunar Node
1303        if should_calculate("Mean_Node"):
1304            cls._calculate_single_planet(data, "Mean_Node", 10, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1305
1306        # Calculate True Lunar Node
1307        if should_calculate("True_Node"):
1308            cls._calculate_single_planet(data, "True_Node", 11, julian_day, iflag, houses_degree_ut, point_type, calculated_planets, active_points)
1309
1310        # Calculate Mean South Node (opposite to Mean North Node)
1311        if should_calculate("Mean_South_Node") and "mean_node" in data:
1312            mean_south_node_deg = math.fmod(data["mean_node"].abs_pos + 180, 360)
1313            data["mean_south_node"] = get_kerykeion_point_from_degree(
1314                mean_south_node_deg, "Mean_South_Node", point_type=point_type
1315            )
1316            data["mean_south_node"].house = get_planet_house(mean_south_node_deg, houses_degree_ut)
1317            data["mean_south_node"].retrograde = data["mean_node"].retrograde
1318            calculated_planets.append("Mean_South_Node")
1319
1320        # Calculate True South Node (opposite to True North Node)
1321        if should_calculate("True_South_Node") and "true_node" in data:
1322            true_south_node_deg = math.fmod(data["true_node"].abs_pos + 180, 360)
1323            data["true_south_node"] = get_kerykeion_point_from_degree(
1324                true_south_node_deg, "True_South_Node", point_type=point_type
1325            )
1326            data["true_south_node"].house = get_planet_house(true_south_node_deg, houses_degree_ut)
1327            data["true_south_node"].retrograde = data["true_node"].retrograde
1328            calculated_planets.append("True_South_Node")
1329
1330        # ==================
1331        # LILITH POINTS
1332        # ==================
1333
1334        # Calculate Mean Lilith (Mean Black Moon)
1335        if should_calculate("Mean_Lilith"):
1336            cls._calculate_single_planet(
1337                data, "Mean_Lilith", 12, julian_day, iflag, houses_degree_ut,
1338                point_type, calculated_planets, active_points
1339            )
1340
1341        # Calculate True Lilith (Osculating Black Moon)
1342        if should_calculate("True_Lilith"):
1343            cls._calculate_single_planet(
1344                data, "True_Lilith", 13, julian_day, iflag, houses_degree_ut,
1345                point_type, calculated_planets, active_points
1346            )
1347
1348        # ==================
1349        # SPECIAL POINTS
1350        # ==================
1351
1352        # Calculate Earth - useful for heliocentric charts
1353        if should_calculate("Earth"):
1354            cls._calculate_single_planet(
1355                data, "Earth", 14, julian_day, iflag, houses_degree_ut,
1356                point_type, calculated_planets, active_points
1357            )
1358
1359        # Calculate Chiron
1360        if should_calculate("Chiron"):
1361            cls._calculate_single_planet(
1362                data, "Chiron", 15, julian_day, iflag, houses_degree_ut,
1363                point_type, calculated_planets, active_points
1364            )
1365
1366        # Calculate Pholus
1367        if should_calculate("Pholus"):
1368            cls._calculate_single_planet(
1369                data, "Pholus", 16, julian_day, iflag, houses_degree_ut,
1370                point_type, calculated_planets, active_points
1371            )
1372
1373        # ==================
1374        # ASTEROIDS
1375        # ==================
1376
1377        # Calculate Ceres
1378        if should_calculate("Ceres"):
1379            cls._calculate_single_planet(
1380                data, "Ceres", 17, julian_day, iflag, houses_degree_ut,
1381                point_type, calculated_planets, active_points
1382            )
1383
1384        # Calculate Pallas
1385        if should_calculate("Pallas"):
1386            cls._calculate_single_planet(
1387                data, "Pallas", 18, julian_day, iflag, houses_degree_ut,
1388                point_type, calculated_planets, active_points
1389            )
1390
1391        # Calculate Juno
1392        if should_calculate("Juno"):
1393            cls._calculate_single_planet(
1394                data, "Juno", 19, julian_day, iflag, houses_degree_ut,
1395                point_type, calculated_planets, active_points
1396            )
1397
1398        # Calculate Vesta
1399        if should_calculate("Vesta"):
1400            cls._calculate_single_planet(
1401                data, "Vesta", 20, julian_day, iflag, houses_degree_ut,
1402                point_type, calculated_planets, active_points
1403            )
1404
1405        # ==================
1406        # TRANS-NEPTUNIAN OBJECTS
1407        # ==================
1408
1409        # Calculate Eris
1410        if should_calculate("Eris"):
1411            try:
1412                eris_calc = swe.calc_ut(julian_day, swe.AST_OFFSET + 136199, iflag)[0]
1413                data["eris"] = get_kerykeion_point_from_degree(eris_calc[0], "Eris", point_type=point_type)
1414                data["eris"].house = get_planet_house(eris_calc[0], houses_degree_ut)
1415                data["eris"].retrograde = eris_calc[3] < 0
1416                calculated_planets.append("Eris")
1417            except Exception as e:
1418                logging.warning(f"Could not calculate Eris position: {e}")
1419                active_points.remove("Eris")  # Remove if not calculated
1420
1421        # Calculate Sedna
1422        if should_calculate("Sedna"):
1423            try:
1424                sedna_calc = swe.calc_ut(julian_day, swe.AST_OFFSET + 90377, iflag)[0]
1425                data["sedna"] = get_kerykeion_point_from_degree(sedna_calc[0], "Sedna", point_type=point_type)
1426                data["sedna"].house = get_planet_house(sedna_calc[0], houses_degree_ut)
1427                data["sedna"].retrograde = sedna_calc[3] < 0
1428                calculated_planets.append("Sedna")
1429            except Exception as e:
1430                logging.warning(f"Could not calculate Sedna position: {e}")
1431                active_points.remove("Sedna")
1432
1433        # Calculate Haumea
1434        if should_calculate("Haumea"):
1435            try:
1436                haumea_calc = swe.calc_ut(julian_day, swe.AST_OFFSET + 136108, iflag)[0]
1437                data["haumea"] = get_kerykeion_point_from_degree(haumea_calc[0], "Haumea", point_type=point_type)
1438                data["haumea"].house = get_planet_house(haumea_calc[0], houses_degree_ut)
1439                data["haumea"].retrograde = haumea_calc[3] < 0
1440                calculated_planets.append("Haumea")
1441            except Exception as e:
1442                logging.warning(f"Could not calculate Haumea position: {e}")
1443                active_points.remove("Haumea")  # Remove if not calculated
1444
1445        # Calculate Makemake
1446        if should_calculate("Makemake"):
1447            try:
1448                makemake_calc = swe.calc_ut(julian_day, swe.AST_OFFSET + 136472, iflag)[0]
1449                data["makemake"] = get_kerykeion_point_from_degree(makemake_calc[0], "Makemake", point_type=point_type)
1450                data["makemake"].house = get_planet_house(makemake_calc[0], houses_degree_ut)
1451                data["makemake"].retrograde = makemake_calc[3] < 0
1452                calculated_planets.append("Makemake")
1453            except Exception as e:
1454                logging.warning(f"Could not calculate Makemake position: {e}")
1455                active_points.remove("Makemake")  # Remove if not calculated
1456
1457        # Calculate Ixion
1458        if should_calculate("Ixion"):
1459            try:
1460                ixion_calc = swe.calc_ut(julian_day, swe.AST_OFFSET + 28978, iflag)[0]
1461                data["ixion"] = get_kerykeion_point_from_degree(ixion_calc[0], "Ixion", point_type=point_type)
1462                data["ixion"].house = get_planet_house(ixion_calc[0], houses_degree_ut)
1463                data["ixion"].retrograde = ixion_calc[3] < 0
1464                calculated_planets.append("Ixion")
1465            except Exception as e:
1466                logging.warning(f"Could not calculate Ixion position: {e}")
1467                active_points.remove("Ixion")  # Remove if not calculated
1468
1469        # Calculate Orcus
1470        if should_calculate("Orcus"):
1471            try:
1472                orcus_calc = swe.calc_ut(julian_day, swe.AST_OFFSET + 90482, iflag)[0]
1473                data["orcus"] = get_kerykeion_point_from_degree(orcus_calc[0], "Orcus", point_type=point_type)
1474                data["orcus"].house = get_planet_house(orcus_calc[0], houses_degree_ut)
1475                data["orcus"].retrograde = orcus_calc[3] < 0
1476                calculated_planets.append("Orcus")
1477            except Exception as e:
1478                logging.warning(f"Could not calculate Orcus position: {e}")
1479                active_points.remove("Orcus")  # Remove if not calculated
1480
1481        # Calculate Quaoar
1482        if should_calculate("Quaoar"):
1483            try:
1484                quaoar_calc = swe.calc_ut(julian_day, swe.AST_OFFSET + 50000, iflag)[0]
1485                data["quaoar"] = get_kerykeion_point_from_degree(quaoar_calc[0], "Quaoar", point_type=point_type)
1486                data["quaoar"].house = get_planet_house(quaoar_calc[0], houses_degree_ut)
1487                data["quaoar"].retrograde = quaoar_calc[3] < 0
1488                calculated_planets.append("Quaoar")
1489            except Exception as e:
1490                logging.warning(f"Could not calculate Quaoar position: {e}")
1491                active_points.remove("Quaoar")  # Remove if not calculated
1492
1493        # ==================
1494        # FIXED STARS
1495        # ==================
1496
1497        # Calculate Regulus (example fixed star)
1498        if should_calculate("Regulus"):
1499            try:
1500                star_name = "Regulus"
1501                swe.fixstar_ut(star_name, julian_day, iflag)
1502                regulus_deg = swe.fixstar_ut(star_name, julian_day, iflag)[0][0]
1503                data["regulus"] = get_kerykeion_point_from_degree(regulus_deg, "Regulus", point_type=point_type)
1504                data["regulus"].house = get_planet_house(regulus_deg, houses_degree_ut)
1505                data["regulus"].retrograde = False  # Fixed stars are never retrograde
1506                calculated_planets.append("Regulus")
1507            except Exception as e:
1508                logging.warning(f"Could not calculate Regulus position: {e}")
1509                active_points.remove("Regulus")  # Remove if not calculated
1510
1511        # Calculate Spica (example fixed star)
1512        if should_calculate("Spica"):
1513            try:
1514                star_name = "Spica"
1515                swe.fixstar_ut(star_name, julian_day, iflag)
1516                spica_deg = swe.fixstar_ut(star_name, julian_day, iflag)[0][0]
1517                data["spica"] = get_kerykeion_point_from_degree(spica_deg, "Spica", point_type=point_type)
1518                data["spica"].house = get_planet_house(spica_deg, houses_degree_ut)
1519                data["spica"].retrograde = False  # Fixed stars are never retrograde
1520                calculated_planets.append("Spica")
1521            except Exception as e:
1522                logging.warning(f"Could not calculate Spica position: {e}")
1523                active_points.remove("Spica")  # Remove if not calculated
1524
1525        # ==================
1526        # ARABIC PARTS / LOTS
1527        # ==================
1528
1529        # Calculate Pars Fortunae (Part of Fortune)
1530        if should_calculate("Pars_Fortunae"):
1531            # Auto-activate required points with notification
1532            required_points: List[AstrologicalPoint] = ["Ascendant", "Sun", "Moon"]
1533            missing_points = [point for point in required_points if point not in active_points]
1534            if missing_points:
1535                logging.info(f"Automatically adding required points for Pars_Fortunae: {missing_points}")
1536                active_points.extend(cast(List[AstrologicalPoint], missing_points))
1537                # Recalculate the missing points
1538                for point in missing_points:
1539                    if point == "Sun" and point not in data:
1540                        sun_calc = swe.calc_ut(julian_day, 0, iflag)[0]
1541                        data["sun"] = get_kerykeion_point_from_degree(sun_calc[0], "Sun", point_type=point_type)
1542                        data["sun"].house = get_planet_house(sun_calc[0], houses_degree_ut)
1543                        data["sun"].retrograde = sun_calc[3] < 0
1544                    elif point == "Moon" and point not in data:
1545                        moon_calc = swe.calc_ut(julian_day, 1, iflag)[0]
1546                        data["moon"] = get_kerykeion_point_from_degree(moon_calc[0], "Moon", point_type=point_type)
1547                        data["moon"].house = get_planet_house(moon_calc[0], houses_degree_ut)
1548                        data["moon"].retrograde = moon_calc[3] < 0
1549
1550            # Check if required points are available
1551            if all(k in data for k in ["ascendant", "sun", "moon"]):
1552                # Different calculation for day and night charts
1553                # Day birth (Sun above horizon): ASC + Moon - Sun
1554                # Night birth (Sun below horizon): ASC + Sun - Moon
1555                if data["sun"].house:
1556                    is_day_chart = get_house_number(data["sun"].house) < 7  # Houses 1-6 are above horizon
1557                else:
1558                    is_day_chart = True  # Default to day chart if house is None
1559
1560                if is_day_chart:
1561                    fortune_deg = math.fmod(data["ascendant"].abs_pos + data["moon"].abs_pos - data["sun"].abs_pos, 360)
1562                else:
1563                    fortune_deg = math.fmod(data["ascendant"].abs_pos + data["sun"].abs_pos - data["moon"].abs_pos, 360)
1564
1565                data["pars_fortunae"] = get_kerykeion_point_from_degree(fortune_deg, "Pars_Fortunae", point_type=point_type)
1566                data["pars_fortunae"].house = get_planet_house(fortune_deg, houses_degree_ut)
1567                data["pars_fortunae"].retrograde = False  # Parts are never retrograde
1568                calculated_planets.append("Pars_Fortunae")
1569
1570        # Calculate Pars Spiritus (Part of Spirit)
1571        if should_calculate("Pars_Spiritus"):
1572            # Auto-activate required points with notification
1573            required_points: List[AstrologicalPoint] = ["Ascendant", "Sun", "Moon"]
1574            missing_points = [point for point in required_points if point not in active_points]
1575            if missing_points:
1576                logging.info(f"Automatically adding required points for Pars_Spiritus: {missing_points}")
1577                active_points.extend(cast(List[AstrologicalPoint], missing_points))
1578                # Recalculate the missing points
1579                for point in missing_points:
1580                    if point == "Sun" and point not in data:
1581                        sun_calc = swe.calc_ut(julian_day, 0, iflag)[0]
1582                        data["sun"] = get_kerykeion_point_from_degree(sun_calc[0], "Sun", point_type=point_type)
1583                        data["sun"].house = get_planet_house(sun_calc[0], houses_degree_ut)
1584                        data["sun"].retrograde = sun_calc[3] < 0
1585                    elif point == "Moon" and point not in data:
1586                        moon_calc = swe.calc_ut(julian_day, 1, iflag)[0]
1587                        data["moon"] = get_kerykeion_point_from_degree(moon_calc[0], "Moon", point_type=point_type)
1588                        data["moon"].house = get_planet_house(moon_calc[0], houses_degree_ut)
1589                        data["moon"].retrograde = moon_calc[3] < 0
1590
1591            # Check if required points are available
1592            if all(k in data for k in ["ascendant", "sun", "moon"]):
1593                # Day birth: ASC + Sun - Moon
1594                # Night birth: ASC + Moon - Sun
1595                if data["sun"].house:
1596                    is_day_chart = get_house_number(data["sun"].house) < 7
1597                else:
1598                    is_day_chart = True  # Default to day chart if house is None
1599
1600                if is_day_chart:
1601                    spirit_deg = math.fmod(data["ascendant"].abs_pos + data["sun"].abs_pos - data["moon"].abs_pos, 360)
1602                else:
1603                    spirit_deg = math.fmod(data["ascendant"].abs_pos + data["moon"].abs_pos - data["sun"].abs_pos, 360)
1604
1605                data["pars_spiritus"] = get_kerykeion_point_from_degree(spirit_deg, "Pars_Spiritus", point_type=point_type)
1606                data["pars_spiritus"].house = get_planet_house(spirit_deg, houses_degree_ut)
1607                data["pars_spiritus"].retrograde = False
1608                calculated_planets.append("Pars_Spiritus")
1609
1610        # Calculate Pars Amoris (Part of Eros/Love)
1611        if should_calculate("Pars_Amoris"):
1612            # Auto-activate required points with notification
1613            required_points: List[AstrologicalPoint] = ["Ascendant", "Venus", "Sun"]
1614            missing_points = [point for point in required_points if point not in active_points]
1615            if missing_points:
1616                logging.info(f"Automatically adding required points for Pars_Amoris: {missing_points}")
1617                active_points.extend(cast(List[AstrologicalPoint], missing_points))
1618                # Recalculate the missing points
1619                for point in missing_points:
1620                    if point == "Sun" and point not in data:
1621                        sun_calc = swe.calc_ut(julian_day, 0, iflag)[0]
1622                        data["sun"] = get_kerykeion_point_from_degree(sun_calc[0], "Sun", point_type=point_type)
1623                        data["sun"].house = get_planet_house(sun_calc[0], houses_degree_ut)
1624                        data["sun"].retrograde = sun_calc[3] < 0
1625                    elif point == "Venus" and point not in data:
1626                        venus_calc = swe.calc_ut(julian_day, 3, iflag)[0]
1627                        data["venus"] = get_kerykeion_point_from_degree(venus_calc[0], "Venus", point_type=point_type)
1628                        data["venus"].house = get_planet_house(venus_calc[0], houses_degree_ut)
1629                        data["venus"].retrograde = venus_calc[3] < 0
1630
1631            # Check if required points are available
1632            if all(k in data for k in ["ascendant", "venus", "sun"]):
1633                # ASC + Venus - Sun
1634                amoris_deg = math.fmod(data["ascendant"].abs_pos + data["venus"].abs_pos - data["sun"].abs_pos, 360)
1635
1636                data["pars_amoris"] = get_kerykeion_point_from_degree(amoris_deg, "Pars_Amoris", point_type=point_type)
1637                data["pars_amoris"].house = get_planet_house(amoris_deg, houses_degree_ut)
1638                data["pars_amoris"].retrograde = False
1639                calculated_planets.append("Pars_Amoris")
1640
1641        # Calculate Pars Fidei (Part of Faith)
1642        if should_calculate("Pars_Fidei"):
1643            # Auto-activate required points with notification
1644            required_points: List[AstrologicalPoint] = ["Ascendant", "Jupiter", "Saturn"]
1645            missing_points = [point for point in required_points if point not in active_points]
1646            if missing_points:
1647                logging.info(f"Automatically adding required points for Pars_Fidei: {missing_points}")
1648                active_points.extend(cast(List[AstrologicalPoint], missing_points))
1649                # Recalculate the missing points
1650                for point in missing_points:
1651                    if point == "Jupiter" and point not in data:
1652                        jupiter_calc = swe.calc_ut(julian_day, 5, iflag)[0]
1653                        data["jupiter"] = get_kerykeion_point_from_degree(jupiter_calc[0], "Jupiter", point_type=point_type)
1654                        data["jupiter"].house = get_planet_house(jupiter_calc[0], houses_degree_ut)
1655                        data["jupiter"].retrograde = jupiter_calc[3] < 0
1656                    elif point == "Saturn" and point not in data:
1657                        saturn_calc = swe.calc_ut(julian_day, 6, iflag)[0]
1658                        data["saturn"] = get_kerykeion_point_from_degree(saturn_calc[0], "Saturn", point_type=point_type)
1659                        data["saturn"].house = get_planet_house(saturn_calc[0], houses_degree_ut)
1660                        data["saturn"].retrograde = saturn_calc[3] < 0
1661
1662            # Check if required points are available
1663            if all(k in data for k in ["ascendant", "jupiter", "saturn"]):
1664                # ASC + Jupiter - Saturn
1665                fidei_deg = math.fmod(data["ascendant"].abs_pos + data["jupiter"].abs_pos - data["saturn"].abs_pos, 360)
1666
1667                data["pars_fidei"] = get_kerykeion_point_from_degree(fidei_deg, "Pars_Fidei", point_type=point_type)
1668                data["pars_fidei"].house = get_planet_house(fidei_deg, houses_degree_ut)
1669                data["pars_fidei"].retrograde = False
1670                calculated_planets.append("Pars_Fidei")
1671
1672        # Calculate Vertex (a sort of auxiliary Descendant)
1673        if should_calculate("Vertex"):
1674            try:
1675                # Vertex is at ascmc[3] in Swiss Ephemeris
1676                if data["zodiac_type"] == "Sidereal":
1677                    _, ascmc = swe.houses_ex(
1678                        tjdut=data["julian_day"],
1679                        lat=data["lat"],
1680                        lon=data["lng"],
1681                        hsys=str.encode("V"),  # Vertex works best with Vehlow system
1682                        flags=swe.FLG_SIDEREAL
1683                    )
1684                else:
1685                    _, ascmc = swe.houses(
1686                        tjdut=data["julian_day"],
1687                        lat=data["lat"],
1688                        lon=data["lng"],
1689                        hsys=str.encode("V")
1690                    )
1691
1692                vertex_deg = ascmc[3]
1693                data["vertex"] = get_kerykeion_point_from_degree(vertex_deg, "Vertex", point_type=point_type)
1694                data["vertex"].house = get_planet_house(vertex_deg, houses_degree_ut)
1695                data["vertex"].retrograde = False
1696                calculated_planets.append("Vertex")
1697
1698                # Calculate Anti-Vertex (opposite to Vertex)
1699                anti_vertex_deg = math.fmod(vertex_deg + 180, 360)
1700                data["anti_vertex"] = get_kerykeion_point_from_degree(anti_vertex_deg, "Anti_Vertex", point_type=point_type)
1701                data["anti_vertex"].house = get_planet_house(anti_vertex_deg, houses_degree_ut)
1702                data["anti_vertex"].retrograde = False
1703                calculated_planets.append("Anti_Vertex")
1704            except Exception as e:
1705                logging.warning("Could not calculate Vertex position, error: %s", e)
1706                active_points.remove("Vertex")
1707
1708        # Store only the planets that were actually calculated
1709        data["active_points"] = calculated_planets
1710
1711    @classmethod
1712    def _calculate_day_of_week(cls, data: Dict[str, Any]) -> None:
1713        """
1714        Calculate the day of the week for the given astronomical event.
1715
1716        Determines the day of the week corresponding to the Julian Day Number
1717        of the astrological event using Swiss Ephemeris calendar functions.
1718
1719        Args:
1720            data (Dict[str, Any]): Calculation data dictionary containing julian_day.
1721                Updated with the calculated day_of_week string.
1722
1723        Side Effects:
1724            Updates data dictionary with:
1725            - day_of_week: Human-readable day name (e.g., "Monday", "Tuesday")
1726
1727        Note:
1728            The Swiss Ephemeris day_of_week function returns an integer where
1729            0=Monday, 1=Tuesday, ..., 6=Sunday. This is converted to readable
1730            day names for user convenience.
1731        """
1732        # Calculate the day of the week (0=Sunday, 1=Monday, ..., 6=Saturday)
1733        day_of_week = swe.day_of_week(data["julian_day"])
1734        # Map to human-readable names
1735        days_of_week = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
1736        data["day_of_week"] = days_of_week[day_of_week]