kerykeion 5.0.0a9__py3-none-any.whl → 5.1.8__py3-none-any.whl

kerykeion/house_comparison/house_comparison_factory.py

@@ -1,30 +1,45 @@
+"""
+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, DEFAULT_ACTIVE_ASPECTS
-from kerykeion.house_comparison.house_comparison_models import HouseComparisonModel
+from kerykeion.settings.config_constants import DEFAULT_ACTIVE_POINTS
+from kerykeion.schemas.kr_models import HouseComparisonModel
 from kerykeion.astrological_subject_factory import AstrologicalSubjectFactory
-from kerykeion.kr_types import AstrologicalSubjectModel, PlanetReturnModel
-from kerykeion.kr_types.kr_literals import AstrologicalPoint
+from kerykeion.schemas import AstrologicalSubjectModel, PlanetReturnModel
+from kerykeion.schemas.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_utils.py

@@ -1,9 +1,19 @@
-from kerykeion.astrological_subject_factory import AstrologicalSubjectFactory
-from kerykeion.kr_types.kr_models import AstrologicalSubjectModel, PlanetReturnModel
-from kerykeion.kr_types.kr_literals import AstrologicalPoint
+"""
+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.schemas.kr_models import AstrologicalSubjectModel, PlanetReturnModel, PointInHouseModel
+from kerykeion.schemas.kr_literals import AstrologicalPoint
 from kerykeion.settings.config_constants import DEFAULT_ACTIVE_POINTS
 from kerykeion.utilities import get_planet_house, get_house_number
-from kerykeion.house_comparison.house_comparison_models import PointInHouseModel
 from typing import Union
 
 
@@ -13,15 +23,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, ["Sun", "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/__init__.py

@@ -1,10 +1,70 @@
 # -*- coding: utf-8 -*-
 """
-    This is part of Kerykeion (C) 2025 Giacomo Battaglia
+Backward compatibility module for Kerykeion v4.x imports.
+
+DEPRECATED: This module will be removed in Kerykeion v6.0.
+Please update your imports:
+    OLD: from kerykeion.kr_types import ...
+    NEW: from kerykeion.schemas import ...
 """
+import warnings
+
+# Issue deprecation warning when this module is imported
+warnings.warn(
+    "The 'kerykeion.kr_types' module is deprecated and will be removed in v6.0. "
+    "Please update your imports to use 'kerykeion.schemas' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Re-export everything from schemas for backward compatibility
+from kerykeion.schemas import *  # noqa: F401, F403
+from kerykeion.schemas.kerykeion_exception import *  # noqa: F401, F403
+from kerykeion.schemas.kr_literals import *  # noqa: F401, F403
+from kerykeion.schemas.kr_models import *  # noqa: F401, F403
+from kerykeion.schemas.settings_models import *  # noqa: F401, F403
+from kerykeion.schemas.chart_template_model import *  # noqa: F401, F403
 
-from .kerykeion_exception import KerykeionException
-from .kr_literals import *
-from .kr_models import *
-from .chart_types import ChartTemplateDictionary
-from .settings_models import KerykeionSettingsModel
+__all__ = [
+    # Re-export from schemas
+    "KerykeionException",
+    # kr_literals
+    "ZodiacType",
+    "Sign",
+    "SignNumbers",
+    "AspectMovementType",
+    "Houses",
+    "HouseNumbers",
+    "AstrologicalPoint",
+    "Element",
+    "Quality",
+    "ChartType",
+    "PointType",
+    "LunarPhaseEmoji",
+    "LunarPhaseName",
+    "SiderealMode",
+    "HousesSystemIdentifier",
+    "PerspectiveType",
+    "SignsEmoji",
+    "KerykeionChartTheme",
+    "KerykeionChartLanguage",
+    "RelationshipScoreDescription",
+    "CompositeChartType",
+    "AspectName",
+    # kr_models
+    "AstrologicalSubjectModel",
+    "CompositeSubjectModel",
+    "KerykeionPointModel",
+    "AspectModel",
+    "ActiveAspect",
+    "SingleChartAspectsModel",
+    "DualChartAspectsModel",
+    "ElementDistributionModel",
+    "QualityDistributionModel",
+    "SingleChartDataModel",
+    "DualChartDataModel",
+    # settings_models
+    "KerykeionSettingsModel",
+    # chart_template_model
+    "ChartTemplateModel",
+]

kerykeion/kr_types/chart_template_model.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""
+Backward compatibility module for chart_template_model.
+
+DEPRECATED: This module will be removed in Kerykeion v6.0.
+Please update your imports:
+    OLD: from kerykeion.kr_types.chart_template_model import ...
+    NEW: from kerykeion.schemas.chart_template_model import ...
+"""
+import warnings
+
+warnings.warn(
+    "The 'kerykeion.kr_types.chart_template_model' module is deprecated and will be removed in v6.0. "
+    "Please update your imports to use 'kerykeion.schemas.chart_template_model' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Re-export everything from schemas.chart_template_model for backward compatibility
+from kerykeion.schemas.chart_template_model import *  # noqa: F401, F403

kerykeion/kr_types/kerykeion_exception.py

@@ -1,14 +1,20 @@
 # -*- coding: utf-8 -*-
 """
-    This is part of Kerykeion (C) 2025 Giacomo Battaglia
-"""
+Backward compatibility module for kerykeion_exception.
 
+DEPRECATED: This module will be removed in Kerykeion v6.0.
+Please update your imports:
+    OLD: from kerykeion.kr_types.kerykeion_exception import ...
+    NEW: from kerykeion.schemas.kerykeion_exception import ...
+"""
+import warnings
 
-class KerykeionException(Exception):
-    """
-    Custom Kerykeion Exception
-    """
+warnings.warn(
+    "The 'kerykeion.kr_types.kerykeion_exception' module is deprecated and will be removed in v6.0. "
+    "Please update your imports to use 'kerykeion.schemas.kerykeion_exception' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
-    def __init__(self, message):
-        # Call the base class constructor with the parameters it needs
-        super().__init__(message)
+# Re-export everything from schemas.kerykeion_exception for backward compatibility
+from kerykeion.schemas.kerykeion_exception import *  # noqa: F401, F403

kerykeion/kr_types/kr_literals.py

@@ -1,166 +1,20 @@
 # -*- coding: utf-8 -*-
 """
-This is part of Kerykeion (C) 2025 Giacomo Battaglia
-"""
-from typing import Literal
-
-
-ZodiacType = Literal["Tropic", "Sidereal"]
-"""Literal type for Zodiac Types"""
-
-
-Sign = Literal["Ari", "Tau", "Gem", "Can", "Leo", "Vir", "Lib", "Sco", "Sag", "Cap", "Aqu", "Pis"]
-"""Literal type for Zodiac Signs"""
-
-
-SignNumbers = Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
-"""Literal type for Zodiac Sign Numbers, the signs are numbered in order starting from Aries (0) to Pis (11)"""
-
-
-Houses = Literal["First_House", "Second_House", "Third_House", "Fourth_House", "Fifth_House", "Sixth_House", "Seventh_House", "Eighth_House", "Ninth_House", "Tenth_House", "Eleventh_House", "Twelfth_House"]
-"""Literal type for Houses"""
-
-
-HouseNumbers = Literal[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
-"""Literal type for House Numbers, starting from the First House (1) to the Twelfth House (12)"""
-
-
-AstrologicalPoint = Literal[
-    # Main Planets
-    "Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto",
-
-    # Nodes
-    "Mean_Node", "True_Node", "Mean_South_Node", "True_South_Node",
-
-    # Special Points
-    "Chiron", "Mean_Lilith", "True_Lilith", "Earth", "Pholus",
-
-    # Asteroids
-    "Ceres", "Pallas", "Juno", "Vesta",
-
-    # Trans-Neptunian Objects
-    "Eris", "Sedna", "Haumea", "Makemake", "Ixion", "Orcus", "Quaoar",
-
-    # Fixed Stars
-    "Regulus", "Spica",
-
-    # Arabic Parts
-    "Pars_Fortunae", "Pars_Spiritus", "Pars_Amoris", "Pars_Fidei",
-
-    # Special Points
-    "Vertex", "Anti_Vertex",
-
-    # Axial Cusps
-    "Ascendant", "Medium_Coeli", "Descendant", "Imum_Coeli",
-]
-
-"""Literal type for Axial Cusps"""
-
-
-Element = Literal["Air", "Fire", "Earth", "Water"]
-"""Literal type for Elements"""
-
-
-Quality = Literal["Cardinal", "Fixed", "Mutable"]
-"""Literal type for Qualities"""
-
+Backward compatibility module for kr_literals.
 
-ChartType = Literal["Natal", "ExternalNatal", "Synastry", "Transit", "Composite", "Return", "SingleWheelReturn"]
-"""Literal type for Chart Types"""
-
-
-PointType = Literal["AstrologicalPoint", "House"]
-"""Literal type for Point Types"""
-
-
-LunarPhaseEmoji = Literal["🌑", "🌒", "🌓", "🌔", "🌕", "🌖", "🌗", "🌘"]
-"""Literal type for Lunar Phases Emoji"""
-
-
-LunarPhaseName = Literal["New Moon", "Waxing Crescent", "First Quarter", "Waxing Gibbous", "Full Moon", "Waning Gibbous", "Last Quarter", "Waning Crescent"]
-"""Literal type for Lunar Phases Name"""
-
-
-SiderealMode = Literal["FAGAN_BRADLEY", "LAHIRI", "DELUCE", "RAMAN", "USHASHASHI", "KRISHNAMURTI", "DJWHAL_KHUL", "YUKTESHWAR", "JN_BHASIN", "BABYL_KUGLER1", "BABYL_KUGLER2", "BABYL_KUGLER3", "BABYL_HUBER", "BABYL_ETPSC", "ALDEBARAN_15TAU", "HIPPARCHOS", "SASSANIAN", "J2000", "J1900", "B1950"]
-"""Literal type for Sidereal Modes, as known as Ayanamsa"""
-
-
-HousesSystemIdentifier = Literal["A", "B", "C", "D", "F", "H", "I", "i", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y"]
+DEPRECATED: This module will be removed in Kerykeion v6.0.
+Please update your imports:
+    OLD: from kerykeion.kr_types.kr_literals import ...
+    NEW: from kerykeion.schemas.kr_literals import ...
 """
-Literal type for Houses Systems:
-
-A = equal
-B = Alcabitius
-C = Campanus
-D = equal (MC)
-F = Carter poli-equ.
-H = horizon/azimut
-I = Sunshine
-i = Sunshine/alt.
-K = Koch
-L = Pullen SD
-M = Morinus
-N = equal/1=Aries
-O = Porphyry
-P = Placidus
-Q = Pullen SR
-R = Regiomontanus
-S = Sripati
-T = Polich/Page
-U = Krusinski-Pisa-Goelzer
-V = equal/Vehlow
-W = equal/whole sign
-X = axial rotation system/Meridian houses
-Y = APC houses
-
-Usually the standard is Placidus (P)
-"""
-
-
-PerspectiveType = Literal["Apparent Geocentric", "Heliocentric", "Topocentric", "True Geocentric"]
-"""
-Literal type for perspective types.
-- "Apparent Geocentric": Earth-centered, apparent positions.
-- "Heliocentric": Sun-centered.
-- "Topocentric": Observer's location on Earth's surface.
-- "True Geocentric": Earth-centered, true positions.
-
-Usually the standard is "Apparent Geocentric"
-"""
-
-
-SignsEmoji = Literal["♈️", "♉️", "♊️", "♋️", "♌️", "♍️", "♎️", "♏️", "♐️", "♑️", "♒️", "♓️"]
-"""Literal type for Zodiac Signs Emoji"""
-
-KerykeionChartTheme = Literal["light", "dark", "dark-high-contrast", "classic", "strawberry"]
-"""Literal type for Kerykeion Chart Themes"""
-
-
-KerykeionChartLanguage = Literal["EN", "FR", "PT", "IT", "CN", "ES", "RU", "TR", "DE", "HI"]
-"""Literal type for Kerykeion Chart Languages"""
-
-
-RelationshipScoreDescription = Literal["Minimal", "Medium", "Important", "Very Important", "Exceptional", "Rare Exceptional"]
-"""Literal type for Relationship Score Description"""
-
-
-CompositeChartType = Literal["Midpoint"]
-"""Literal type for Composite Chart Types"""
+import warnings
 
-AspectName = Literal[
-    "conjunction",
-    "semi-sextile",
-    "semi-square",
-    "sextile",
-    "quintile",
-    "square",
-    "trine",
-    "sesquiquadrate",
-    "biquintile",
-    "quincunx",
-    "opposition"
-]
-"""Literal type for all the available aspects names"""
+warnings.warn(
+    "The 'kerykeion.kr_types.kr_literals' module is deprecated and will be removed in v6.0. "
+    "Please update your imports to use 'kerykeion.schemas.kr_literals' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
-ReturnType = Literal["Lunar", "Solar"]
-"""Literal type for Return Types"""
+# Re-export everything from schemas.kr_literals for backward compatibility
+from kerykeion.schemas.kr_literals import *  # noqa: F401, F403