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

kerykeion/charts/kerykeion_chart_svg.py

@@ -64,7 +64,7 @@ from kerykeion.charts.charts_utils import (
     calculate_quality_points,
     calculate_synastry_quality_points
 )
-from kerykeion.charts.draw_planets_v2 import draw_planets_v2 as draw_planets
+from kerykeion.charts.draw_planets import draw_planets
 from kerykeion.utilities import get_houses_list, inline_css_variables_in_svg
 from kerykeion.settings.config_constants import DEFAULT_ACTIVE_ASPECTS
 from kerykeion.settings.legacy.legacy_color_settings import DEFAULT_CHART_COLORS
@@ -314,7 +314,6 @@ class KerykeionChartSVG:
             # Calculate aspects
             natal_aspects_instance = NatalAspectsFactory.from_subject(
                 self.first_obj,
-                new_settings_file=self.new_settings_file,
                 active_points=self.active_points,
                 active_aspects=active_aspects,
             )
@@ -347,7 +346,7 @@ class KerykeionChartSVG:
                 raise KerykeionException("First object must be a CompositeSubjectModel instance.")
 
             # Calculate aspects
-            self.aspects_list = NatalAspectsFactory.from_subject(self.first_obj, new_settings_file=self.new_settings_file, active_points=self.active_points).relevant_aspects
+            self.aspects_list = NatalAspectsFactory.from_subject(self.first_obj, active_points=self.active_points).relevant_aspects
 
             # Screen size
             self.height = self._DEFAULT_HEIGHT
@@ -381,7 +380,6 @@ class KerykeionChartSVG:
             synastry_aspects_instance = SynastryAspectsFactory.from_subjects(
                 self.first_obj,
                 self.second_obj,
-                new_settings_file=self.new_settings_file,
                 active_points=self.active_points,
                 active_aspects=active_aspects,
             )
@@ -426,7 +424,6 @@ class KerykeionChartSVG:
             synastry_aspects_instance = SynastryAspectsFactory.from_subjects(
                 self.first_obj,
                 self.second_obj,
-                new_settings_file=self.new_settings_file,
                 active_points=self.active_points,
                 active_aspects=active_aspects,
             )
@@ -467,7 +464,6 @@ class KerykeionChartSVG:
             synastry_aspects_instance = SynastryAspectsFactory.from_subjects(
                 self.first_obj,
                 self.second_obj,
-                new_settings_file=self.new_settings_file,
                 active_points=self.active_points,
                 active_aspects=active_aspects,
             )
@@ -500,7 +496,6 @@ class KerykeionChartSVG:
             # Calculate aspects
             natal_aspects_instance = NatalAspectsFactory.from_subject(
                 self.first_obj,
-                new_settings_file=self.new_settings_file,
                 active_points=self.active_points,
                 active_aspects=active_aspects,
             )

kerykeion/charts/templates/wheel_only.xml

@@ -5,7 +5,7 @@
     xmlns:kr="https://www.kerykeion.net/"
     width="100%"
     height="100%"
-    viewBox="85 40 500 500"
+    viewBox="90 40 500 500"
     preserveAspectRatio="xMidYMid"
     style="background-color: $background_color"
 >

kerykeion/composite_subject_factory.py

@@ -1,3 +1,43 @@
+"""
+Composite Subject Factory Module
+
+This module provides functionality for creating composite astrological charts from two
+individual astrological subjects. A composite chart represents the relationship between
+two people by calculating midpoint positions between corresponding planetary placements
+and house cusps.
+
+The module implements the midpoint composite technique, which is the most commonly used
+method for relationship astrology. This technique creates a single chart that symbolizes
+the energy and dynamics of the relationship itself, rather than comparing individual charts.
+
+Key Features:
+- Midpoint calculation for all planetary positions
+- Midpoint calculation for house cusp positions
+- Proper handling of zodiacal boundary crossings (0°/360°)
+- Validation of compatible astrological settings between subjects
+- Lunar phase calculation for composite charts
+- Support for all standard astrological points and house systems
+
+Classes:
+    CompositeSubjectFactory: Main factory class for creating composite charts
+
+Dependencies:
+    - AstrologicalSubjectFactory: For working with individual astrological subjects
+    - Various kr_types modules: For type definitions and models
+    - utilities module: For astrological calculations and helper functions
+
+Example Usage:
+    >>> from kerykeion import AstrologicalSubjectFactory, CompositeSubjectFactory
+    >>> person1 = AstrologicalSubjectFactory.from_birth_data(...)
+    >>> person2 = AstrologicalSubjectFactory.from_birth_data(...)
+    >>> composite = CompositeSubjectFactory(person1, person2)
+    >>> composite_chart = composite.get_midpoint_composite_subject_model()
+
+Author: Giacomo Battaglia
+Copyright: (C) 2025 Kerykeion Project
+License: AGPL-3.0
+"""
+
 from typing import Union
 
 # Fix the circular import by changing this import
@@ -17,15 +57,48 @@ from kerykeion.utilities import (
 
 class CompositeSubjectFactory:
     """
-    Factory class to create a Composite Subject Model from two Astrological Subjects
-    Currently, the only available method for creating composite charts is the midpoint method.
-    The composite houses and planets are calculated based on the midpoint of the corresponding points of the two subjects.
-    The house are then reordered to match the original house system of the first subject.
-
-    Args:
-        first_subject (AstrologicalSubject): First astrological subject
-        second_subject (AstrologicalSubject): Second astrological subject
-        chart_name (str): Name of the composite chart. If None, it will be automatically generated.
+    Factory class to create composite astrological charts from two astrological subjects.
+
+    A composite chart represents the relationship between two people by calculating the midpoint
+    between corresponding planetary positions and house cusps. This creates a single chart
+    that symbolizes the energy of the relationship itself.
+
+    Currently supports the midpoint method for composite chart calculation, where:
+    - Planetary positions are calculated as the circular mean of corresponding planets
+    - House cusps are calculated as the circular mean of corresponding houses
+    - Houses are reordered to maintain consistency with the original house system
+    - Only common active points between both subjects are included
+
+    The resulting composite chart maintains the zodiac type, sidereal mode, houses system,
+    and perspective type of the input subjects (which must be identical between subjects).
+
+    Attributes:
+        model (CompositeSubjectModel | None): The generated composite subject model
+        first_subject (AstrologicalSubjectModel): First astrological subject
+        second_subject (AstrologicalSubjectModel): Second astrological subject
+        name (str): Name of the composite chart
+        composite_chart_type (CompositeChartType): Type of composite chart (currently "Midpoint")
+        zodiac_type (ZodiacType): Zodiac system used (Tropical or Sidereal)
+        sidereal_mode (SiderealMode | None): Sidereal calculation mode if applicable
+        houses_system_identifier (HousesSystemIdentifier): House system identifier
+        houses_system_name (str): Human-readable house system name
+        perspective_type (PerspectiveType): Astrological perspective type
+        houses_names_list (list[Houses]): List of house names
+        active_points (list[AstrologicalPoint]): Common active planetary points
+
+    Example:
+        >>> first_person = AstrologicalSubjectFactory.from_birth_data(
+        ...     "John", 1990, 1, 1, 12, 0, "New York", "US"
+        ... )
+        >>> second_person = AstrologicalSubjectFactory.from_birth_data(
+        ...     "Jane", 1992, 6, 15, 14, 30, "Los Angeles", "US"
+        ... )
+        >>> composite = CompositeSubjectFactory(first_person, second_person)
+        >>> composite_model = composite.get_midpoint_composite_subject_model()
+
+    Raises:
+        KerykeionException: When subjects have incompatible settings (different zodiac types,
+                           sidereal modes, house systems, or perspective types)
     """
 
     model: Union[CompositeSubjectModel, None]
@@ -47,6 +120,27 @@ class CompositeSubjectFactory:
             second_subject: AstrologicalSubjectModel,
             chart_name: Union[str, None] = None
     ):
+        """
+        Initialize the composite subject factory with two astrological subjects.
+
+        Validates that both subjects have compatible settings and extracts common
+        active points for composite chart calculation.
+
+        Args:
+            first_subject (AstrologicalSubjectModel): First astrological subject for the composite
+            second_subject (AstrologicalSubjectModel): Second astrological subject for the composite
+            chart_name (str | None, optional): Custom name for the composite chart.
+                                             If None, generates name from subject names.
+                                             Defaults to None.
+
+        Raises:
+            KerykeionException: If subjects have different zodiac types, sidereal modes,
+                              house systems, house system names, or perspective types.
+
+        Note:
+            Both subjects must have identical astrological calculation settings to ensure
+            meaningful composite chart calculations.
+        """
         self.model: Union[CompositeSubjectModel, None] = None
         self.composite_chart_type = "Midpoint"
 
@@ -102,30 +196,114 @@ class CompositeSubjectFactory:
         self.houses_names_list = self.first_subject.houses_names_list
 
     def __str__(self):
+        """
+        Return string representation of the composite subject.
+
+        Returns:
+            str: Human-readable string describing the composite chart.
+        """
         return f"Composite Chart Data for {self.name}"
 
     def __repr__(self):
+        """
+        Return detailed string representation of the composite subject.
+
+        Returns:
+            str: Detailed string representation for debugging purposes.
+        """
         return f"Composite Chart Data for {self.name}"
 
     def __eq__(self, other):
+        """
+        Check equality with another composite subject.
+
+        Args:
+            other (CompositeSubjectFactory): Another composite subject to compare with.
+
+        Returns:
+            bool: True if both subjects and chart name are identical.
+        """
         return self.first_subject == other.first_subject and self.second_subject == other.second_subject and self.name == other.chart_name
 
     def __ne__(self, other):
+        """
+        Check inequality with another composite subject.
+
+        Args:
+            other (CompositeSubjectFactory): Another composite subject to compare with.
+
+        Returns:
+            bool: True if subjects or chart name are different.
+        """
         return not self.__eq__(other)
 
     def __hash__(self):
+        """
+        Generate hash for the composite subject.
+
+        Returns:
+            int: Hash value based on both subjects and chart name.
+        """
         return hash((self.first_subject, self.second_subject, self.name))
 
     def __copy__(self):
+        """
+        Create a shallow copy of the composite subject.
+
+        Returns:
+            CompositeSubjectFactory: New instance with the same subjects and name.
+        """
         return CompositeSubjectFactory(self.first_subject, self.second_subject, self.name)
 
     def __setitem__(self, key, value):
+        """
+        Set an attribute using dictionary-style access.
+
+        Args:
+            key (str): Attribute name to set.
+            value: Value to assign to the attribute.
+        """
         setattr(self, key, value)
 
     def __getitem__(self, key):
+        """
+        Get an attribute using dictionary-style access.
+
+        Args:
+            key (str): Attribute name to retrieve.
+
+        Returns:
+            Any: Value of the requested attribute.
+
+        Raises:
+            AttributeError: If the attribute doesn't exist.
+        """
         return getattr(self, key)
 
     def _calculate_midpoint_composite_points_and_houses(self):
+        """
+        Calculate midpoint positions for all planets and house cusps in the composite chart.
+
+        This method implements the midpoint composite technique by:
+        1. Computing circular means of house cusp positions from both subjects
+        2. Sorting house positions to maintain proper house order
+        3. Creating composite house cusps with calculated positions
+        4. Computing circular means of planetary positions for common active points
+        5. Assigning planets to their appropriate houses in the composite chart
+
+        The circular mean calculation ensures proper handling of zodiacal positions
+        around the 360-degree boundary (e.g., when one position is at 350° and
+        another at 10°, the midpoint is correctly calculated as 0°).
+
+        Side Effects:
+            - Updates instance attributes with calculated house cusp positions
+            - Updates instance attributes with calculated planetary positions
+            - Sets house assignments for each planetary position
+
+        Note:
+            This is an internal method called by get_midpoint_composite_subject_model().
+            Only planets that exist in both subjects' active_points are included.
+        """
         # Houses
         house_degree_list_ut = []
         for house in self.first_subject.houses_names_list:
@@ -165,12 +343,53 @@ class CompositeSubjectFactory:
             self[planet_lower]["house"] = get_planet_house(self[planet_lower]['abs_pos'], house_degree_list_ut)
 
     def _calculate_composite_lunar_phase(self):
+        """
+        Calculate the lunar phase for the composite chart based on Sun-Moon midpoints.
+
+        Uses the composite positions of the Sun and Moon to determine the lunar phase
+        angle, representing the relationship's emotional and instinctual dynamics.
+
+        Side Effects:
+            Sets the lunar_phase attribute with the calculated phase information.
+
+        Note:
+            This method should be called after _calculate_midpoint_composite_points_and_houses()
+            to ensure Sun and Moon composite positions are available.
+        """
         self.lunar_phase = calculate_moon_phase(
             self['moon'].abs_pos,
             self['sun'].abs_pos
         )
 
     def get_midpoint_composite_subject_model(self):
+        """
+        Generate the complete composite chart model using the midpoint technique.
+
+        This is the main public method for creating a composite chart. It orchestrates
+        the calculation of all composite positions and creates a complete CompositeSubjectModel
+        containing all necessary astrological data for the relationship chart.
+
+        The process includes:
+        1. Calculating midpoint positions for all planets and house cusps
+        2. Computing the composite lunar phase
+        3. Assembling all data into a comprehensive model
+
+        Returns:
+            CompositeSubjectModel: Complete composite chart data model containing:
+                - All calculated planetary positions and their house placements
+                - House cusp positions maintaining proper house system order
+                - Lunar phase information for the composite chart
+                - All metadata from the original subjects (names, chart type, etc.)
+
+        Example:
+            >>> composite = CompositeSubjectFactory(person1, person2, "Our Relationship")
+            >>> model = composite.get_midpoint_composite_subject_model()
+            >>> print(f"Composite Sun at {model.sun.abs_pos}° in House {model.sun.house}")
+
+        Note:
+            This method performs all calculations internally and returns a complete,
+            ready-to-use composite chart model suitable for analysis or chart drawing.
+        """
         self._calculate_midpoint_composite_points_and_houses()
         self._calculate_composite_lunar_phase()