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

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/kerykeion_exception.py

@@ -10,5 +10,11 @@ class KerykeionException(Exception):
     """
 
     def __init__(self, message):
+        """
+        Initialize a new KerykeionException.
+
+        Args:
+            message: The error message to be displayed.
+        """
         # Call the base class constructor with the parameters it needs
         super().__init__(message)

kerykeion/kr_types/kr_models.py

@@ -34,19 +34,33 @@ class SubscriptableBaseModel(BaseModel):
     """
 
     def __getitem__(self, key):
+        """Get an attribute using dictionary-style access."""
         return getattr(self, key)
 
     def __setitem__(self, key, value):
+        """Set an attribute using dictionary-style access."""
         setattr(self, key, value)
 
     def __delitem__(self, key):
+        """Delete an attribute using dictionary-style access."""
         delattr(self, key)
 
     def get(self, key, default = None):
+        """Get an attribute with a default value if not found."""
         return getattr(self, key, default)
 
 
 class LunarPhaseModel(SubscriptableBaseModel):
+    """
+    Model representing lunar phase information.
+
+    Attributes:
+        degrees_between_s_m: Angular separation between Sun and Moon in degrees.
+        moon_phase: Numerical phase identifier for the Moon.
+        sun_phase: Numerical phase identifier for the Sun.
+        moon_emoji: Emoji representation of the lunar phase.
+        moon_phase_name: Text name of the lunar phase.
+    """
     degrees_between_s_m: Union[float, int]
     moon_phase: int
     sun_phase: int
@@ -56,7 +70,24 @@ class LunarPhaseModel(SubscriptableBaseModel):
 
 class KerykeionPointModel(SubscriptableBaseModel):
     """
-    Kerykeion Point Model
+    Model representing an astrological celestial point or house cusp.
+
+    This model contains comprehensive information about celestial objects
+    (planets, points) or house cusps including their zodiacal position,
+    sign placement, and metadata.
+
+    Attributes:
+        name: The name of the celestial point or house.
+        quality: Astrological quality (Cardinal, Fixed, Mutable).
+        element: Astrological element (Fire, Earth, Air, Water).
+        sign: The zodiac sign the point is located in.
+        sign_num: Numerical identifier for the zodiac sign (0-11).
+        position: Position within the sign (0-30 degrees).
+        abs_pos: Absolute position in the zodiac (0-360 degrees).
+        emoji: Unicode emoji representing the point or sign.
+        point_type: Type of the celestial point (Planet, House, etc.).
+        house: House placement of the point (optional).
+        retrograde: Whether the point is in retrograde motion (optional).
     """
 
     name: Union[AstrologicalPoint, Houses]
@@ -74,7 +105,29 @@ class KerykeionPointModel(SubscriptableBaseModel):
 
 class AstrologicalBaseModel(SubscriptableBaseModel):
     """
-    Base Model with common fields for all astrological subjects
+    Base model containing common fields for all astrological subjects.
+
+    This model serves as the foundation for all astrological chart types,
+    providing standard location, time, and configuration data. It supports
+    both complete charts (with full location/time data) and composite charts
+    (where some fields may be optional).
+
+    Attributes:
+        name: Subject identifier or name.
+        city: Location city (optional for composite charts).
+        nation: Country code (optional for composite charts).
+        lng: Longitude coordinate (optional for composite charts).
+        lat: Latitude coordinate (optional for composite charts).
+        tz_str: Timezone string (optional for composite charts).
+        iso_formatted_local_datetime: Local datetime in ISO format (optional).
+        iso_formatted_utc_datetime: UTC datetime in ISO format (optional).
+        julian_day: Julian day number for astronomical calculations (optional).
+        day_of_week: Day of the week (optional).
+        zodiac_type: Type of zodiac system used (Tropical or Sidereal).
+        sidereal_mode: Sidereal calculation mode (if applicable).
+        houses_system_identifier: House system used for calculations.
+        perspective_type: Astrological perspective (geocentric, heliocentric, etc.).
+        active_points: List of celestial points included in calculations.
     """
     # Common identification data
     name: str
@@ -285,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.