kerykeion 5.0.0a10__py3-none-any.whl → 5.0.0a11__py3-none-any.whl

kerykeion/relationship_score_factory.py

@@ -1,6 +1,44 @@
 # -*- coding: utf-8 -*-
 """
-    This is part of Kerykeion (C) 2025 Giacomo Battaglia
+Relationship Score Factory Module
+
+This module calculates relationship scores between two astrological subjects using the
+Ciro Discepolo method. It analyzes synastry aspects to generate numerical compatibility
+scores with descriptive categories.
+
+Key Features:
+    - Point-based scoring system using synastry aspects
+    - Configurable major/minor aspect filtering
+    - Orbital precision weighting
+    - Categorical score descriptions
+
+Score Categories:
+    - 0-5: Minimal relationship
+    - 5-10: Medium relationship
+    - 10-15: Important relationship
+    - 15-20: Very important relationship
+    - 20-30: Exceptional relationship
+    - 30+: Rare exceptional relationship
+
+Classes:
+    RelationshipScoreFactory: Main factory for calculating relationship scores
+
+Example:
+    >>> from kerykeion import AstrologicalSubjectFactory
+    >>> from kerykeion.relationship_score_factory import RelationshipScoreFactory
+    >>>
+    >>> person1 = AstrologicalSubjectFactory.from_birth_data("John", 1990, 5, 15, 12, 0, "New York", "US")
+    >>> person2 = AstrologicalSubjectFactory.from_birth_data("Jane", 1988, 8, 22, 14, 30, "London", "GB")
+    >>> factory = RelationshipScoreFactory(person1, person2)
+    >>> score = factory.get_relationship_score()
+    >>> print(f"Score: {score.score_value} ({score.score_description})")
+
+Reference:
+    Ciro Discepolo Method: http://www.cirodiscepolo.it/Articoli/Discepoloele.htm
+
+Author: Giacomo Battaglia
+Copyright: (C) 2025 Kerykeion Project
+License: AGPL-3.0
 """
 
 from kerykeion import AstrologicalSubjectFactory
@@ -22,21 +60,26 @@ VENUS_MARS_ASPECT_POINTS = 4
 
 class RelationshipScoreFactory:
     """
-    Calculates the relevance of the relationship between two subjects using the Ciro Discepolo method.
+    Calculates relationship scores between two subjects using the Ciro Discepolo method.
 
-    Results:
-        - 0 to 5: Minimal relationship
-        - 5 to 10: Medium relationship
-        - 10 to 15: Important relationship
-        - 15 to 20: Very important relationship
-        - 20 to 35: Exceptional relationship
-        - 30 and above: Rare Exceptional relationship
+    The scoring system evaluates synastry aspects between planetary positions to generate
+    numerical compatibility scores with categorical descriptions.
 
-    Documentation: http://www.cirodiscepolo.it/Articoli/Discepoloele.htm
+    Score Ranges:
+        - 0-5: Minimal relationship
+        - 5-10: Medium relationship
+        - 10-15: Important relationship
+        - 15-20: Very important relationship
+        - 20-30: Exceptional relationship
+        - 30+: Rare exceptional relationship
 
     Args:
-        first_subject (AstrologicalSubjectModel): First subject instance
-        second_subject (AstrologicalSubjectModel): Second subject instance
+        first_subject (AstrologicalSubjectModel): First astrological subject
+        second_subject (AstrologicalSubjectModel): Second astrological subject
+        use_only_major_aspects (bool, optional): Filter to major aspects only. Defaults to True.
+
+    Reference:
+        http://www.cirodiscepolo.it/Articoli/Discepoloele.htm
     """
 
     SCORE_MAPPING = [
@@ -68,7 +111,10 @@ class RelationshipScoreFactory:
 
     def _evaluate_destiny_sign(self):
         """
-        Evaluates if the subjects share the same sun sign quality and adds points if true.
+        Checks if subjects share the same sun sign quality and adds points.
+
+        Adds 5 points if both subjects have sun signs with matching quality
+        (cardinal, fixed, or mutable).
         """
         if self.first_subject.sun["quality"] == self.second_subject.sun["quality"]: # type: ignore
             self.is_destiny_sign = True
@@ -77,11 +123,11 @@ class RelationshipScoreFactory:
 
     def _evaluate_aspect(self, aspect, points):
         """
-        Evaluates an aspect and adds points to the score.
+        Processes an aspect and adds points to the total score.
 
         Args:
-            aspect (dict): Aspect information.
-            points (int): Points to add.
+            aspect (dict): Aspect data containing planetary positions and geometry
+            points (int): Points to add to the total score
         """
         if self.use_only_major_aspects and aspect["aspect"] not in self.MAJOR_ASPECTS:
             return
@@ -99,12 +145,12 @@ class RelationshipScoreFactory:
 
     def _evaluate_sun_sun_main_aspect(self, aspect):
         """
-        Evaluates Sun-Sun main aspects and adds points accordingly:
-        - 8 points for conjunction/opposition/square
-        - 11 points if the aspect's orbit is <= 2 degrees
+        Evaluates Sun-Sun conjunction, opposition, or square aspects.
+
+        Adds 8 points for standard orbs, 11 points for tight orbs (≤2°).
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if aspect["p1_name"] == "Sun" and aspect["p2_name"] == "Sun" and aspect["aspect"] in {"conjunction", "opposition", "square"}:
             points = MAJOR_ASPECT_POINTS_HIGH_PRECISION if aspect["orbit"] <= HIGH_PRECISION_ORBIT_THRESHOLD else MAJOR_ASPECT_POINTS_STANDARD
@@ -112,12 +158,12 @@ class RelationshipScoreFactory:
 
     def _evaluate_sun_moon_conjunction(self, aspect):
         """
-        Evaluates Sun-Moon conjunctions and adds points accordingly:
-        - 8 points for conjunction
-        - 11 points if the aspect's orbit is <= 2 degrees
+        Evaluates Sun-Moon conjunction aspects.
+
+        Adds 8 points for standard orbs, 11 points for tight orbs (≤2°).
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if {aspect["p1_name"], aspect["p2_name"]} == {"Moon", "Sun"} and aspect["aspect"] == "conjunction":
             points = MAJOR_ASPECT_POINTS_HIGH_PRECISION if aspect["orbit"] <= HIGH_PRECISION_ORBIT_THRESHOLD else MAJOR_ASPECT_POINTS_STANDARD
@@ -125,11 +171,12 @@ class RelationshipScoreFactory:
 
     def _evaluate_sun_sun_other_aspects(self, aspect):
         """
-        Evaluates Sun-Sun aspects that are not conjunctions and adds points accordingly:
-        - 4 points for other aspects
+        Evaluates Sun-Sun aspects other than conjunction, opposition, or square.
+
+        Adds 4 points for any qualifying aspect.
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if aspect["p1_name"] == "Sun" and aspect["p2_name"] == "Sun" and aspect["aspect"] not in {"conjunction", "opposition", "square"}:
             points = MINOR_ASPECT_POINTS
@@ -137,11 +184,12 @@ class RelationshipScoreFactory:
 
     def _evaluate_sun_moon_other_aspects(self, aspect):
         """
-        Evaluates Sun-Moon aspects that are not conjunctions and adds points accordingly:
-        - 4 points for other aspects
+        Evaluates Sun-Moon aspects other than conjunctions.
+
+        Adds 4 points for any qualifying aspect.
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if {aspect["p1_name"], aspect["p2_name"]} == {"Moon", "Sun"} and aspect["aspect"] != "conjunction":
             points = MINOR_ASPECT_POINTS
@@ -149,11 +197,12 @@ class RelationshipScoreFactory:
 
     def _evaluate_sun_ascendant_aspect(self, aspect):
         """
-        Evaluates Sun-Ascendant aspects and adds points accordingly:
-        - 4 points for any aspect
+        Evaluates Sun-Ascendant aspects.
+
+        Adds 4 points for any aspect between Sun and Ascendant.
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if {aspect["p1_name"], aspect["p2_name"]} == {"Sun", "Ascendant"}:
             points = SUN_ASCENDANT_ASPECT_POINTS
@@ -161,11 +210,12 @@ class RelationshipScoreFactory:
 
     def _evaluate_moon_ascendant_aspect(self, aspect):
         """
-        Evaluates Moon-Ascendant aspects and adds points accordingly:
-        - 4 points for any aspect
+        Evaluates Moon-Ascendant aspects.
+
+        Adds 4 points for any aspect between Moon and Ascendant.
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if {aspect["p1_name"], aspect["p2_name"]} == {"Moon", "Ascendant"}:
             points = MOON_ASCENDANT_ASPECT_POINTS
@@ -173,11 +223,12 @@ class RelationshipScoreFactory:
 
     def _evaluate_venus_mars_aspect(self, aspect):
         """
-        Evaluates Venus-Mars aspects and adds points accordingly:
-        - 4 points for any aspect
+        Evaluates Venus-Mars aspects.
+
+        Adds 4 points for any aspect between Venus and Mars.
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if {aspect["p1_name"], aspect["p2_name"]} == {"Venus", "Mars"}:
             points = VENUS_MARS_ASPECT_POINTS
@@ -185,7 +236,9 @@ class RelationshipScoreFactory:
 
     def _evaluate_relationship_score_description(self):
         """
-        Evaluates the relationship score description based on the total score.
+        Determines the categorical description based on the numerical score.
+
+        Maps the total score to predefined description ranges.
         """
         for description, threshold in self.SCORE_MAPPING:
             if self.score_value < threshold:
@@ -194,10 +247,11 @@ class RelationshipScoreFactory:
 
     def get_relationship_score(self):
         """
-        Calculates the relationship score based on synastry aspects.
+        Calculates the complete relationship score using all evaluation methods.
 
         Returns:
-            RelationshipScoreModel: The calculated relationship score.
+            RelationshipScoreModel: Score object containing numerical value, description,
+                destiny sign status, contributing aspects, and subject data.
         """
         self._evaluate_destiny_sign()
 

kerykeion/report.py

@@ -14,6 +14,12 @@ class Report:
     houses_table: str
 
     def __init__(self, instance: AstrologicalSubjectModel):
+        """
+        Initialize a new Report instance.
+
+        Args:
+            instance: The astrological subject model to create a report for.
+        """
         self.instance = instance
 
         self.get_report_title()
@@ -22,6 +28,7 @@ class Report:
         self.get_houses_table()
 
     def get_report_title(self) -> None:
+        """Generate the report title based on the subject's name."""
         self.report_title = f"\n+- Kerykeion report for {self.instance.name} -+"
 
     def get_data_table(self) -> None:

kerykeion/transits_time_range_factory.py

@@ -0,0 +1,293 @@
+"""
+Transits Time Range Factory Module
+
+This module provides the TransitsTimeRangeFactory class for calculating astrological
+transits over specified time periods. It compares ephemeris data points (planetary
+positions at different times) with a natal chart to identify when celestial bodies
+form specific angular relationships (aspects).
+
+Key Features:
+    - Time-series transit calculations
+    - Configurable celestial points and aspect types
+    - Structured output models for data analysis
+    - Integration with ephemeris data generation
+    - Batch processing of multiple time points
+
+The module generates comprehensive transit data by analyzing the angular relationships
+between transiting celestial bodies and natal chart positions, creating timestamped
+records of when specific geometric configurations occur.
+
+Classes:
+    TransitsTimeRangeFactory: Main factory class for generating transit data
+
+Dependencies:
+    - kerykeion.AstrologicalSubjectFactory: For creating astrological subjects
+    - kerykeion.aspects.SynastryAspectsFactory: For calculating angular relationships
+    - kerykeion.ephemeris_data_factory: For generating time-series planetary positions
+    - kerykeion.kr_types: For type definitions and model structures
+    - datetime: For date/time handling
+
+Example:
+    Basic usage for calculating 30-day transits:
+
+    >>> from datetime import datetime, timedelta
+    >>> from kerykeion import AstrologicalSubjectFactory
+    >>> from kerykeion.ephemeris_data_factory import EphemerisDataFactory
+    >>> from kerykeion.transits_time_range_factory import TransitsTimeRangeFactory
+    >>>
+    >>> # Create natal chart
+    >>> person = AstrologicalSubjectFactory.from_birth_data(
+    ...     "Subject", 1990, 1, 1, 12, 0, "New York", "US"
+    ... )
+    >>>
+    >>> # Generate ephemeris data
+    >>> start = datetime.now()
+    >>> end = start + timedelta(days=30)
+    >>> ephemeris_factory = EphemerisDataFactory(start, end)
+    >>> ephemeris_data = ephemeris_factory.get_ephemeris_data_as_astrological_subjects()
+    >>>
+    >>> # Calculate transits
+    >>> transit_factory = TransitsTimeRangeFactory(person, ephemeris_data)
+    >>> results = transit_factory.get_transit_moments()
+
+Author: Giacomo Battaglia
+Copyright: (C) 2025 Kerykeion Project
+License: AGPL-3.0
+"""
+
+from typing import Union, List
+from datetime import datetime, timedelta
+from kerykeion.kr_types.kr_models import AstrologicalSubjectModel
+from kerykeion.astrological_subject_factory import AstrologicalSubjectFactory
+from kerykeion.aspects import SynastryAspectsFactory
+from kerykeion.ephemeris_data_factory import EphemerisDataFactory
+from kerykeion.kr_types.kr_literals import AstrologicalPoint
+from kerykeion.kr_types.kr_models import ActiveAspect, TransitMomentModel, TransitsTimeRangeModel
+from kerykeion.kr_types.settings_models import KerykeionSettingsModel
+from kerykeion.settings.config_constants import DEFAULT_ACTIVE_POINTS, DEFAULT_ACTIVE_ASPECTS
+from pathlib import Path
+
+
+class TransitsTimeRangeFactory:
+    """
+    Factory class for calculating astrological transits over time periods.
+
+    This class analyzes the angular relationships (aspects) between transiting
+    celestial bodies and natal chart positions across multiple time points,
+    generating structured transit data for astrological analysis.
+
+    The factory compares ephemeris data points (representing planetary positions
+    at different moments) with a natal chart to identify when specific geometric
+    configurations occur between transiting and natal celestial bodies.
+
+    Args:
+        natal_chart (AstrologicalSubjectModel): The natal chart used as the reference
+            point for transit calculations. All transiting positions are compared
+            against this chart's planetary positions.
+        ephemeris_data_points (List[AstrologicalSubjectModel]): A list of astrological
+            subject models representing different moments in time, typically generated
+            by EphemerisDataFactory. Each point contains planetary positions for
+            a specific date/time.
+        active_points (List[AstrologicalPoint], optional): List of celestial bodies
+            to include in aspect calculations (e.g., Sun, Moon, planets, asteroids).
+            Defaults to DEFAULT_ACTIVE_POINTS.
+        active_aspects (List[ActiveAspect], optional): List of aspect types to
+            calculate (e.g., conjunction, opposition, trine, square, sextile).
+            Defaults to DEFAULT_ACTIVE_ASPECTS.
+        settings_file (Union[Path, KerykeionSettingsModel, dict, None], optional):
+            Configuration settings for calculations. Can be a file path, settings
+            model, dictionary, or None for defaults. Defaults to None.
+
+    Attributes:
+        natal_chart: The reference natal chart for transit calculations.
+        ephemeris_data_points: Time-series planetary position data.
+        active_points: Celestial bodies included in calculations.
+        active_aspects: Aspect types considered for analysis.
+        settings_file: Configuration settings for the calculations.
+
+    Examples:
+        Basic transit calculation:
+
+        >>> natal_chart = AstrologicalSubjectFactory.from_birth_data(...)
+        >>> ephemeris_data = ephemeris_factory.get_ephemeris_data_as_astrological_subjects()
+        >>> factory = TransitsTimeRangeFactory(natal_chart, ephemeris_data)
+        >>> transits = factory.get_transit_moments()
+
+        Custom configuration:
+
+        >>> from kerykeion.kr_types import AstrologicalPoint, ActiveAspect
+        >>> custom_points = [AstrologicalPoint.SUN, AstrologicalPoint.MOON]
+        >>> custom_aspects = [ActiveAspect.CONJUNCTION, ActiveAspect.OPPOSITION]
+        >>> factory = TransitsTimeRangeFactory(
+        ...     natal_chart, ephemeris_data,
+        ...     active_points=custom_points,
+        ...     active_aspects=custom_aspects
+        ... )
+
+    Note:
+        - Calculation time scales with the number of ephemeris data points
+        - More active points and aspects increase computational requirements
+        - The natal chart's coordinate system should match the ephemeris data
+    """
+
+    def __init__(
+        self,
+        natal_chart: AstrologicalSubjectModel,
+        ephemeris_data_points: List[AstrologicalSubjectModel],
+        active_points: List[AstrologicalPoint] = DEFAULT_ACTIVE_POINTS,
+        active_aspects: List[ActiveAspect] = DEFAULT_ACTIVE_ASPECTS,
+        settings_file: Union[Path, KerykeionSettingsModel, dict, None] = None,
+    ):
+        """
+        Initialize the TransitsTimeRangeFactory with calculation parameters.
+
+        Sets up the factory with all necessary data and configuration for calculating
+        transits across the specified time period. The natal chart serves as the
+        reference point, while ephemeris data points provide the transiting positions
+        for comparison.
+
+        Args:
+            natal_chart (AstrologicalSubjectModel): Reference natal chart containing
+                the baseline planetary positions for transit calculations.
+            ephemeris_data_points (List[AstrologicalSubjectModel]): Time-ordered list
+                of planetary positions representing different moments in time.
+                Typically generated by EphemerisDataFactory.
+            active_points (List[AstrologicalPoint], optional): Celestial bodies to
+                include in aspect calculations. Determines which planets/points are
+                analyzed for aspects. Defaults to DEFAULT_ACTIVE_POINTS.
+            active_aspects (List[ActiveAspect], optional): Types of angular relationships
+                to calculate between natal and transiting positions. Defaults to
+                DEFAULT_ACTIVE_ASPECTS.
+            settings_file (Union[Path, KerykeionSettingsModel, dict, None], optional):
+                Configuration settings for orb tolerances, calculation methods, and
+                other parameters. Defaults to None (uses system defaults).
+
+        Note:
+            - All ephemeris data points should use the same coordinate system as the natal chart
+            - The order of ephemeris_data_points determines the chronological sequence
+            - Settings affect orb tolerances and calculation precision
+        """
+        self.natal_chart = natal_chart
+        self.ephemeris_data_points = ephemeris_data_points
+        self.active_points = active_points
+        self.active_aspects = active_aspects
+        self.settings_file = settings_file
+
+    def get_transit_moments(self) -> TransitsTimeRangeModel:
+        """
+        Calculate and generate transit data for all configured time points.
+
+        This method processes each ephemeris data point to identify angular relationships
+        (aspects) between transiting celestial bodies and natal chart positions. It
+        creates a comprehensive model containing all transit moments with their
+        corresponding aspects and timestamps.
+
+        The calculation process:
+        1. Iterates through each ephemeris data point chronologically
+        2. Compares transiting planetary positions with natal chart positions
+        3. Identifies aspects that fall within the configured orb tolerances
+        4. Creates timestamped transit moment records
+        5. Compiles all data into a structured model for analysis
+
+        Returns:
+            TransitsTimeRangeModel: A comprehensive model containing:
+                - dates (List[str]): ISO-formatted datetime strings for all data points
+                - subject (AstrologicalSubjectModel): The natal chart used as reference
+                - transits (List[TransitMomentModel]): Chronological list of transit moments,
+                  each containing:
+                  * date (str): ISO-formatted timestamp for the transit moment
+                  * aspects (List[RelevantAspect]): All aspects formed at this moment
+                    between transiting and natal positions
+
+        Examples:
+            Basic usage:
+
+            >>> factory = TransitsTimeRangeFactory(natal_chart, ephemeris_data)
+            >>> results = factory.get_transit_moments()
+            >>>
+            >>> # Access specific data
+            >>> all_dates = results.dates
+            >>> first_transit = results.transits[0]
+            >>> aspects_at_first_moment = first_transit.aspects
+
+            Processing results:
+
+            >>> results = factory.get_transit_moments()
+            >>> for transit_moment in results.transits:
+            ...     print(f"Date: {transit_moment.date}")
+            ...     for aspect in transit_moment.aspects:
+            ...         print(f"  {aspect.p1_name} {aspect.aspect} {aspect.p2_name}")
+
+        Performance Notes:
+            - Calculation time is proportional to: number of time points × active points × active aspects
+            - Large datasets may require significant processing time
+            - Memory usage scales with the number of aspects found
+            - Consider filtering active_points and active_aspects for better performance
+
+        See Also:
+            TransitMomentModel: Individual transit moment structure
+            TransitsTimeRangeModel: Complete transit dataset structure
+            SynastryAspectsFactory: Underlying aspect calculation engine
+        """
+        transit_moments = []
+
+        for ephemeris_point in self.ephemeris_data_points:
+            # Calculate aspects between transit positions and natal chart
+            aspects = SynastryAspectsFactory.from_subjects(
+                ephemeris_point,
+                self.natal_chart,
+                active_points=self.active_points,
+                active_aspects=self.active_aspects,
+            ).relevant_aspects
+
+            # Create a transit moment for this point in time
+            transit_moments.append(
+                TransitMomentModel(
+                    date=ephemeris_point.iso_formatted_utc_datetime,
+                    aspects=aspects,
+                )
+            )
+
+        # Create and return the complete transits model
+        return TransitsTimeRangeModel(
+            dates=[point.iso_formatted_utc_datetime for point in self.ephemeris_data_points],
+            subject=self.natal_chart,
+            transits=transit_moments
+        )
+
+
+if __name__ == "__main__":
+    # Create a natal chart for the subject
+    person = AstrologicalSubjectFactory.from_birth_data(
+        "Johnny Depp", 1963, 6, 9, 20, 15, "Owensboro", "US"
+    )
+
+    # Define the time period for transit calculation
+    start_date = datetime.now()
+    end_date = datetime.now() + timedelta(days=30)
+
+    # Create ephemeris data for the specified time period
+    ephemeris_factory = EphemerisDataFactory(
+        start_datetime=start_date,
+        end_datetime=end_date,
+        step_type="days",
+        step=1,
+        lat=person.lat,
+        lng=person.lng,
+        tz_str=person.tz_str,
+    )
+
+    ephemeris_data_points = ephemeris_factory.get_ephemeris_data_as_astrological_subjects()
+
+    # Calculate transits for the subject
+    transit_factory = TransitsTimeRangeFactory(
+        natal_chart=person,
+        ephemeris_data_points=ephemeris_data_points,
+    )
+
+    transit_results = transit_factory.get_transit_moments()
+
+    # Print example data
+    print(transit_results.model_dump()["dates"][2])
+    print(transit_results.model_dump()["transits"][2]['date'])
+    print(transit_results.model_dump()["transits"][2]['aspects'][0])