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

kerykeion/house_comparison/house_comparison_factory.py

@@ -1,3 +1,14 @@
+"""
+House Comparison Factory Module
+
+Provides factory class for house comparison analysis between astrological subjects.
+Enables bidirectional analysis of astrological point placements in house systems.
+
+Author: Giacomo Battaglia
+Copyright: (C) 2025 Kerykeion Project
+License: AGPL-3.0
+"""
+
 from kerykeion.house_comparison.house_comparison_utils import calculate_points_in_reciprocal_houses
 from typing import Union
 from kerykeion.settings.config_constants import DEFAULT_ACTIVE_POINTS
@@ -9,22 +20,26 @@ from kerykeion.kr_types.kr_literals import AstrologicalPoint
 
 class HouseComparisonFactory:
     """
-    Factory class for creating house comparison analyses between two astrological charts.
+    Factory for creating house comparison analyses between two astrological subjects.
 
-    This class handles the generation of house comparison data, calculating how planets
-    from one chart interact with the house system of another chart (and vice versa).
-    This is useful for synastry analysis and other forms of relationship astrology.
+    Analyzes placement of astrological points from one subject within the house system
+    of another subject, performing bidirectional analysis for synastry studies and
+    subject comparisons. Supports both natal subjects and planetary return subjects.
 
     Attributes:
-        first_subject (AstrologicalSubject): The first person's astrological chart
-        second_subject (AstrologicalSubject): The second person's astrological chart
+        first_subject: First astrological subject (natal or return subject)
+        second_subject: Second astrological subject (natal or return subject)
+        active_points: List of astrological points to include in analysis
 
     Example:
-        >>> natal_chart = AstrologicalSubjectFactory.from_birth_data("Person A", 1990, 5, 15, 10, 30, "Rome", "IT")
-        >>> partner_chart = AstrologicalSubjectFactory.from_birth_data("Person B", 1992, 8, 23, 14, 45, "Milan", "IT")
+        >>> natal_chart = AstrologicalSubjectFactory.from_birth_data(
+        ...     "Person A", 1990, 5, 15, 10, 30, "Rome", "IT"
+        ... )
+        >>> partner_chart = AstrologicalSubjectFactory.from_birth_data(
+        ...     "Person B", 1992, 8, 23, 14, 45, "Milan", "IT"
+        ... )
         >>> factory = HouseComparisonFactory(natal_chart, partner_chart)
         >>> comparison = factory.get_house_comparison()
-        >>> print(comparison.model_dump_json(indent=4))
 
     """
     def __init__(self,
@@ -33,21 +48,39 @@ class HouseComparisonFactory:
                 active_points: list[AstrologicalPoint] = DEFAULT_ACTIVE_POINTS,
 
         ):
+        """
+        Initialize the house comparison factory.
+
+        Args:
+            first_subject: First astrological subject for comparison
+            second_subject: Second astrological subject for comparison
+            active_points: List of astrological points to include in analysis.
+                          Defaults to standard active points.
+
+        Note:
+            Both subjects must have valid house system data for accurate analysis.
+        """
         self.first_subject = first_subject
         self.second_subject = second_subject
         self.active_points = active_points
 
     def get_house_comparison(self) -> "HouseComparisonModel":
         """
-        Creates a house comparison model for two astrological subjects.
+        Generate bidirectional house comparison analysis between the two subjects.
 
-        Args:
-            chart1: First astrological subject
-            chart2: Second astrological subject
-            description: Description of the comparison
+        Calculates where each active astrological point from one subject falls within
+        the house system of the other subject, and vice versa.
 
         Returns:
-            "HouseComparisonModel": Model containing the comparison data.
+            HouseComparisonModel: Model containing:
+                - first_subject_name: Name of the first subject
+                - second_subject_name: Name of the second subject
+                - first_points_in_second_houses: First subject's points in second subject's houses
+                - second_points_in_first_houses: Second subject's points in first subject's houses
+
+        Note:
+            Analysis scope is determined by the active_points list. Only specified
+            points will be included in the results.
         """
         first_points_in_second_houses = calculate_points_in_reciprocal_houses(self.first_subject, self.second_subject, self.active_points)
         second_points_in_first_houses = calculate_points_in_reciprocal_houses(self.second_subject, self.first_subject, self.active_points)

kerykeion/house_comparison/house_comparison_models.py

@@ -1,38 +1,76 @@
+"""
+House Comparison Data Models
+
+Pydantic models for house comparison analysis results between astrological subjects.
+Structures data output from house comparison calculations.
+
+Author: Giacomo Battaglia
+Copyright: (C) 2025 Kerykeion Project
+License: AGPL-3.0
+"""
+
 from kerykeion.kr_types import SubscriptableBaseModel
 from typing import Optional
 
 
 class PointInHouseModel(SubscriptableBaseModel):
-    """Represents a point from one chart positioned in a house from another chart"""
+    """
+    Represents an astrological point from one subject positioned within another subject's house.
+
+    Captures point characteristics and its placement within the target subject's house system
+    for house comparison analysis.
+
+    Attributes:
+        point_name: Name of the astrological point
+        point_degree: Degree position within its sign
+        point_sign: Zodiacal sign containing the point
+        point_owner_name: Name of the subject who owns this point
+        point_owner_house_number: House number in owner's chart
+        point_owner_house_name: House name in owner's chart
+        projected_house_number: House number in target subject's chart
+        projected_house_name: House name in target subject's chart
+        projected_house_owner_name: Name of the target subject
+    """
 
     point_name: str
-    """Name of the celestial point"""
+    """Name of the astrological point"""
     point_degree: float
-    """Degree of the celestial point"""
+    """Degree position of the point within its zodiacal sign"""
     point_sign: str
-    """Sign of the celestial point"""
+    """Zodiacal sign containing the point"""
     point_owner_name: str
-    """Name of the owner of the celestial point"""
+    """Name of the subject who owns this point"""
     point_owner_house_number: Optional[int]
-    """House number of the point of the owner of the celestial point"""
+    """House number in owner's chart"""
     point_owner_house_name: Optional[str]
-    """House name of the point of the owner of the celestial point"""
+    """House name in owner's chart"""
     projected_house_number: int
-    """Number of the house where the point is projected"""
+    """House number in target subject's chart"""
     projected_house_name: str
-    """Name of the house where the point is projected"""
+    """House name in target subject's chart"""
     projected_house_owner_name: str
-    """Name of the owner of the house where the point is projected"""
+    """Name of the target subject"""
 
 
 class HouseComparisonModel(SubscriptableBaseModel):
-    """Pydantic model for comparing points in houses between two astrological subjects"""
+    """
+    Bidirectional house comparison analysis between two astrological subjects.
+
+    Contains results of how astrological points from each subject interact with
+    the house system of the other subject.
+
+    Attributes:
+        first_subject_name: Name of the first subject
+        second_subject_name: Name of the second subject
+        first_points_in_second_houses: First subject's points in second subject's houses
+        second_points_in_first_houses: Second subject's points in first subject's houses
+    """
 
     first_subject_name: str
     """Name of the first subject"""
     second_subject_name: str
     """Name of the second subject"""
     first_points_in_second_houses: list[PointInHouseModel]
-    """List of points from the first subject in the houses of the second subject"""
+    """First subject's points positioned in second subject's houses"""
     second_points_in_first_houses: list[PointInHouseModel]
-    """List of points from the second subject in the houses of the first subject"""
+    """Second subject's points positioned in first subject's houses"""

kerykeion/house_comparison/house_comparison_utils.py

@@ -1,3 +1,15 @@
+"""
+House Comparison Utilities
+
+Utility functions for calculating house placement relationships between astrological subjects.
+Provides core calculation logic for determining where points from one subject fall within
+another subject's house system.
+
+Author: Giacomo Battaglia
+Copyright: (C) 2025 Kerykeion Project
+License: AGPL-3.0
+"""
+
 from kerykeion.kr_types.kr_models import AstrologicalSubjectModel, PlanetReturnModel
 from kerykeion.kr_types.kr_literals import AstrologicalPoint
 from kerykeion.settings.config_constants import DEFAULT_ACTIVE_POINTS
@@ -12,15 +24,33 @@ def calculate_points_in_reciprocal_houses(
     active_points: list[AstrologicalPoint] = DEFAULT_ACTIVE_POINTS,
 ) -> list[PointInHouseModel]:
     """
-    Calculates which houses of the house_subject the points of point_subject fall into.
+    Calculate house placements of one subject's points within another subject's house system.
+
+    Analyzes where each astrological point from the point_subject falls within the
+    house structure of the house_subject. Creates detailed mapping including both
+    the point's original house position and its projected house placement.
 
     Args:
-        point_subject: Subject whose points are being analyzed
-        house_subject: Subject whose houses are being considered
-        active_points: Optional list of point names to process. If None, all points are processed.
+        point_subject: Subject whose astrological points are being analyzed
+        house_subject: Subject whose house system provides the projection framework
+        active_points: List of astrological points to include in the analysis.
+                      Defaults to standard active points configuration.
 
     Returns:
-        List of PointInHouseModel objects
+        list[PointInHouseModel]: List of point placement models containing detailed
+                                information about each point's house relationships,
+                                including original and projected house positions.
+
+    Note:
+        Only processes points that exist in both the point_subject's active_points
+        and the provided active_points list. Points with None values are skipped.
+
+    Example:
+        >>> points_in_houses = calculate_points_in_reciprocal_houses(
+        ...     natal_chart, partner_chart, [AstrologicalPoint.SUN, AstrologicalPoint.MOON]
+        ... )
+        >>> sun_placement = points_in_houses[0]  # Assuming Sun is first
+        >>> print(f"Sun falls in house: {sun_placement.projected_house_name}")
     """
     points_in_houses: list[PointInHouseModel] = []
 

kerykeion/kr_types/kr_models.py

@@ -338,35 +338,52 @@ class TransitMomentModel(SubscriptableBaseModel):
     aspects: List[AspectModel] = Field(description="List of aspects active at this specific moment.")
 
 
-class NatalAspectsModel(SubscriptableBaseModel):
+class SingleChartAspectsModel(SubscriptableBaseModel):
     """
-    Model representing all aspects in a natal chart.
+    Model representing all aspects within a single astrological chart.
+
+    This model can be used for any type of single chart analysis including:
+    - Natal charts
+    - Planetary return charts
+    - Composite charts
+    - Any other single chart type
 
     Contains both all calculated aspects and the filtered relevant aspects
-    for an astrological subject.
+    for the astrological subject.
     """
     subject: Union["AstrologicalSubjectModel", "CompositeSubjectModel", "PlanetReturnModel"] = Field(description="The astrological subject for which aspects were calculated.")
-    all_aspects: List[AspectModel] = Field(description="Complete list of all calculated aspects.")
+    all_aspects: List[AspectModel] = Field(description="Complete list of all calculated aspects within the chart.")
     relevant_aspects: List[AspectModel] = Field(description="Filtered list of relevant aspects based on orb settings.")
     active_points: List[AstrologicalPoint] = Field(description="List of active points used in the calculation.")
     active_aspects: List["ActiveAspect"] = Field(description="List of active aspects with their orb settings.")
 
 
-class SynastryAspectsModel(SubscriptableBaseModel):
+class DualChartAspectsModel(SubscriptableBaseModel):
     """
-    Model representing all aspects between two astrological subjects.
+    Model representing all aspects between two astrological charts.
+
+    This model can be used for any type of dual chart analysis including:
+    - Synastry (relationship compatibility)
+    - Transit comparisons
+    - Composite vs natal comparisons
+    - Any other dual chart comparison
 
-    Contains both all calculated synastry aspects and the filtered relevant aspects
-    between two charts.
+    Contains both all calculated aspects and the filtered relevant aspects
+    between the two charts.
     """
     first_subject: Union["AstrologicalSubjectModel", "CompositeSubjectModel", "PlanetReturnModel"] = Field(description="The first astrological subject.")
     second_subject: Union["AstrologicalSubjectModel", "CompositeSubjectModel", "PlanetReturnModel"] = Field(description="The second astrological subject.")
-    all_aspects: List[AspectModel] = Field(description="Complete list of all calculated synastry aspects.")
-    relevant_aspects: List[AspectModel] = Field(description="Filtered list of relevant synastry aspects based on orb settings.")
+    all_aspects: List[AspectModel] = Field(description="Complete list of all calculated aspects between the two charts.")
+    relevant_aspects: List[AspectModel] = Field(description="Filtered list of relevant aspects based on orb settings.")
     active_points: List[AstrologicalPoint] = Field(description="List of active points used in the calculation.")
     active_aspects: List["ActiveAspect"] = Field(description="List of active aspects with their orb settings.")
 
 
+# Legacy aliases for backward compatibility
+NatalAspectsModel = SingleChartAspectsModel
+SynastryAspectsModel = DualChartAspectsModel
+
+
 class TransitsTimeRangeModel(SubscriptableBaseModel):
     """
     Model representing a collection of transit moments for an astrological subject.

kerykeion/relationship_score_factory.py

@@ -42,7 +42,7 @@ License: AGPL-3.0
 """
 
 from kerykeion import AstrologicalSubjectFactory
-from kerykeion.aspects.synastry_aspects_factory import SynastryAspectsFactory
+from kerykeion.aspects import AspectsFactory
 import logging
 from kerykeion.kr_types.kr_models import AstrologicalSubjectModel, RelationshipScoreAspectModel, RelationshipScoreModel
 from kerykeion.kr_types.kr_literals import RelationshipScoreDescription
@@ -107,7 +107,7 @@ class RelationshipScoreFactory:
         self.relationship_score_description: RelationshipScoreDescription = "Minimal"
         self.is_destiny_sign = True
         self.relationship_score_aspects: list[RelationshipScoreAspectModel] = []
-        self._synastry_aspects = SynastryAspectsFactory.from_subjects(self.first_subject, self.second_subject).all_aspects
+        self._synastry_aspects = AspectsFactory.dual_chart_aspects(self.first_subject, self.second_subject).all_aspects
 
     def _evaluate_destiny_sign(self):
         """