kerykeion 4.26.2__py3-none-any.whl → 5.0.0a1__py3-none-any.whl

kerykeion/kr_types/settings_models.py

@@ -18,69 +18,10 @@ class KerykeionSettingsCelestialPointModel(SubscriptableBaseModel):
     name: str = Field(title="Celestial Point Name", description="Celestial Point Name")
     color: str = Field(title="Celestial Point Color", description="Celestial Point Color, used in the chart")
     element_points: int = Field(title="Celestial Point Element Points", description="Element Points given to the celestial point")
-    related_zodiac_signs: List[int] = Field(title="Celestial Point Related Zodiac Signs", description="Zodiac Signs related to the celestial point")
     label: str = Field(title="Celestial Point Label", description="The name of the celestial point in the chart, it can be different from the name")
     is_active: Optional[bool] = Field(title="Celestial Point is Active", description="Indicates if the celestial point is active in the chart", default=None)
 
 
-# Chart Colors Settings
-class KerykeionSettingsChartColorsModel(SubscriptableBaseModel):
-    """
-    Defines the model for the chart colors.
-    """
-
-    paper_0: str = Field(title="Paper Color 0", description="Paper Color 0")
-    paper_1: str = Field(title="Paper Color 1", description="Paper Color 1")
-    zodiac_bg_0: str = Field(title="Zodiac Background Color 0", description="Zodiac Background Color 0")
-    zodiac_bg_1: str = Field(title="Zodiac Background Color 1", description="Zodiac Background Color 1")
-    zodiac_bg_2: str = Field(title="Zodiac Background Color 2", description="Zodiac Background Color 2")
-    zodiac_bg_3: str = Field(title="Zodiac Background Color 3", description="Zodiac Background Color 3")
-    zodiac_bg_4: str = Field(title="Zodiac Background Color 4", description="Zodiac Background Color 4")
-    zodiac_bg_5: str = Field(title="Zodiac Background Color 5", description="Zodiac Background Color 5")
-    zodiac_bg_6: str = Field(title="Zodiac Background Color 6", description="Zodiac Background Color 6")
-    zodiac_bg_7: str = Field(title="Zodiac Background Color 7", description="Zodiac Background Color 7")
-    zodiac_bg_8: str = Field(title="Zodiac Background Color 8", description="Zodiac Background Color 8")
-    zodiac_bg_9: str = Field(title="Zodiac Background Color 9", description="Zodiac Background Color 9")
-    zodiac_bg_10: str = Field(title="Zodiac Background Color 10", description="Zodiac Background Color 10")
-    zodiac_bg_11: str = Field(title="Zodiac Background Color 11", description="Zodiac Background Color 11")
-    zodiac_icon_0: str = Field(title="Zodiac Icon Color 0", description="Zodiac Icon Color 0")
-    zodiac_icon_1: str = Field(title="Zodiac Icon Color 1", description="Zodiac Icon Color 1")
-    zodiac_icon_2: str = Field(title="Zodiac Icon Color 2", description="Zodiac Icon Color 2")
-    zodiac_icon_3: str = Field(title="Zodiac Icon Color 3", description="Zodiac Icon Color 3")
-    zodiac_icon_4: str = Field(title="Zodiac Icon Color 4", description="Zodiac Icon Color 4")
-    zodiac_icon_5: str = Field(title="Zodiac Icon Color 5", description="Zodiac Icon Color 5")
-    zodiac_icon_6: str = Field(title="Zodiac Icon Color 6", description="Zodiac Icon Color 6")
-    zodiac_icon_7: str = Field(title="Zodiac Icon Color 7", description="Zodiac Icon Color 7")
-    zodiac_icon_8: str = Field(title="Zodiac Icon Color 8", description="Zodiac Icon Color 8")
-    zodiac_icon_9: str = Field(title="Zodiac Icon Color 9", description="Zodiac Icon Color 9")
-    zodiac_icon_10: str = Field(title="Zodiac Icon Color 10", description="Zodiac Icon Color 10")
-    zodiac_icon_11: str = Field(title="Zodiac Icon Color 11", description="Zodiac Icon Color 11")
-    zodiac_radix_ring_0: str = Field(title="Zodiac Radix Ring Color 0", description="Zodiac Radix Ring Color 0")
-    zodiac_radix_ring_1: str = Field(title="Zodiac Radix Ring Color 1", description="Zodiac Radix Ring Color 1")
-    zodiac_radix_ring_2: str = Field(title="Zodiac Radix Ring Color 2", description="Zodiac Radix Ring Color 2")
-    zodiac_transit_ring_0: str = Field(title="Zodiac Transit Ring Color 0", description="Zodiac Transit Ring Color 0")
-    zodiac_transit_ring_1: str = Field(title="Zodiac Transit Ring Color 1", description="Zodiac Transit Ring Color 1")
-    zodiac_transit_ring_2: str = Field(title="Zodiac Transit Ring Color 2", description="Zodiac Transit Ring Color 2")
-    zodiac_transit_ring_3: str = Field(title="Zodiac Transit Ring Color 3", description="Zodiac Transit Ring Color 3")
-    houses_radix_line: str = Field(title="Houses Radix Line Color", description="Houses Radix Line Color")
-    houses_transit_line: str = Field(title="Houses Transit Line Color", description="Houses Transit Line Color")
-
-    # Deprecated: Not used anymore
-    lunar_phase_0: str = Field(title="Lunar Phase Color 0", description="Lunar Phase Color 0")
-    lunar_phase_1: str = Field(title="Lunar Phase Color 1", description="Lunar Phase Color 1")
-
-
-# Aspect Settings
-class KerykeionSettingsAspectModel(SubscriptableBaseModel):
-    """
-    Defines the model for an aspect.
-    """
-
-    degree: int = Field(title="Aspect Degrees", description="The degree of the aspect")
-    name: str = Field(title="Aspect Name", description="The name of the aspect")
-    color: str = Field(title="Aspect Color", description="The color of the aspect")
-    orb: Optional[int] = Field(title="Aspect Orb", description="The orb of the aspect", default=None)
-
 # Language Settings
 class KerykeionLanguageCelestialPointModel(SubscriptableBaseModel):
     """
@@ -108,7 +49,28 @@ class KerykeionLanguageCelestialPointModel(SubscriptableBaseModel):
     Mean_Lilith: str = Field(title="Mean Lilith", description="The name of Mean Lilith in the chart, in the language")
     True_South_Node: str = Field(title="True South Node", description="The name of True South Node in the chart, in the language")
     Mean_South_Node: str = Field(title="Mean South Node", description="The name of Mean South Node in the chart, in the language")
-
+    True_Lilith: str = Field(title="True Lilith", description="The name of True Lilith in the chart, in the language")
+    Earth: str = Field(title="Earth", description="The name of Earth in the chart, in the language")
+    Pholus: str = Field(title="Pholus", description="The name of Pholus in the chart, in the language")
+    Ceres: str = Field(title="Ceres", description="The name of Ceres in the chart, in the language")
+    Pallas: str = Field(title="Pallas", description="The name of Pallas in the chart, in the language")
+    Juno: str = Field(title="Juno", description="The name of Juno in the chart, in the language")
+    Vesta: str = Field(title="Vesta", description="The name of Vesta in the chart, in the language")
+    Eris: str = Field(title="Eris", description="The name of Eris in the chart, in the language")
+    Sedna: str = Field(title="Sedna", description="The name of Sedna in the chart, in the language")
+    Haumea: str = Field(title="Haumea", description="The name of Haumea in the chart, in the language")
+    Makemake: str = Field(title="Makemake", description="The name of Makemake in the chart, in the language")
+    Ixion: str = Field(title="Ixion", description="The name of Ixion in the chart, in the language")
+    Orcus: str = Field(title="Orcus", description="The name of Orcus in the chart, in the language")
+    Quaoar: str = Field(title="Quaoar", description="The name of Quaoar in the chart, in the language")
+    Regulus: str = Field(title="Regulus", description="The name of Regulus in the chart, in the language")
+    Spica: str = Field(title="Spica", description="The name of Spica in the chart, in the language")
+    Pars_Fortunae: str = Field(title="Part of Fortune", description="The name of Part of Fortune in the chart, in the language")
+    Pars_Spiritus: str = Field(title="Part of Spirit", description="The name of Part of Spirit in the chart, in the language")
+    Pars_Amoris: str = Field(title="Part of Love", description="The name of Part of Love in the chart, in the language")
+    Pars_Fidei: str = Field(title="Part of Faith", description="The name of Part of Faith in the chart, in the language")
+    Vertex: str = Field(title="Vertex", description="The name of Vertex in the chart, in the language")
+    Anti_Vertex: str = Field(title="Anti-Vertex", description="The name of Anti-Vertex in the chart, in the language")
 
 class KerykeionLanguageModel(SubscriptableBaseModel):
     """
@@ -116,93 +78,95 @@ class KerykeionLanguageModel(SubscriptableBaseModel):
     it's used to translate the celestial points and the other labels
     """
 
-    info: str
-    cusp: str
-    longitude: str
-    latitude: str
-    north: str
-    east: str
-    south: str
-    west: str
-    fire: str
-    earth: str
-    air: str
-    water: str
-    and_word: str
-    transits: str
-    type: str
-    couple_aspects: str
-    transit_aspects: str
-    planets_and_house: str
-    transit_name: str
-    lunar_phase: str
-    day: str
-    celestial_points: KerykeionLanguageCelestialPointModel
-    composite_chart: str
-    midpoints: str
-    north_letter: str
-    east_letter: str
-    south_letter: str
-    west_letter: str
-    tropical: str
-    sidereal: str
-    zodiac: str
-    ayanamsa: str
-    apparent_geocentric: str
-    heliocentric: str
-    topocentric: str
-    true_geocentric: str
-    new_moon: str
-    waxing_crescent: str
-    first_quarter: str
-    waxing_gibbous: str
-    full_moon: str
-    waning_gibbous: str
-    last_quarter: str
-    waning_crescent: str
-    houses: str
-    houses_system_A: str
-    houses_system_B: str
-    houses_system_C: str
-    houses_system_D: str
-    houses_system_F: str
-    houses_system_H: str
-    houses_system_I: str
-    houses_system_i: str
-    houses_system_K: str
-    houses_system_L: str
-    houses_system_M: str
-    houses_system_N: str
-    houses_system_O: str
-    houses_system_P: str
-    houses_system_Q: str
-    houses_system_R: str
-    houses_system_S: str
-    houses_system_T: str
-    houses_system_U: str
-    houses_system_V: str
-    houses_system_W: str
-    houses_system_X: str
-    houses_system_Y: str
-    Natal: str
-    ExternalNatal: str
-    Synastry: str
-    Transit: str
-    Composite: str
-
-
-class KerykeionGeneralSettingsModel(SubscriptableBaseModel):
-    axes_orbit: int = Field(title="Axes Orbit", description="The orbit of the axes in the chart")
-
+    info: str = Field(title="Info", description="The info label in the chart, in the language")
+    cusp: str = Field(title="Cusp", description="The cusp label in the chart, in the language")
+    longitude: str = Field(title="Longitude", description="The longitude label in the chart, in the language")
+    latitude: str = Field(title="Latitude", description="The latitude label in the chart, in the language")
+    north: str = Field(title="North", description="The north label in the chart, in the language")
+    east: str = Field(title="East", description="The east label in the chart, in the language")
+    south: str = Field(title="South", description="The south label in the chart, in the language")
+    west: str = Field(title="West", description="The west label in the chart, in the language")
+    fire: str = Field(title="Fire", description="The fire element label in the chart, in the language")
+    earth: str = Field(title="Earth", description="The earth element label in the chart, in the language")
+    air: str = Field(title="Air", description="The air element label in the chart, in the language")
+    water: str = Field(title="Water", description="The water element label in the chart, in the language")
+    and_word: str = Field(title="And", description="The 'and' word in the chart, in the language")
+    transits: str = Field(title="Transits", description="The transits label in the chart, in the language")
+    type: str = Field(title="Type", description="The type label in the chart, in the language")
+    couple_aspects: str = Field(title="Couple Aspects", description="The couple aspects label in the chart, in the language")
+    transit_aspects: str = Field(title="Transit Aspects", description="The transit aspects label in the chart, in the language")
+    planets_and_house: str = Field(title="Planets and House", description="The planets and house label in the chart, in the language")
+    transit_name: str = Field(title="Transit Name", description="The transit name label in the chart, in the language")
+    lunar_phase: str = Field(title="Lunar Phase", description="The lunar phase label in the chart, in the language")
+    lunation_day: str = Field(title="Lunation Day", description="The lunation day label in the chart, in the language")
+    day: str = Field(title="Day", description="The day label in the chart, in the language")
+    celestial_points: KerykeionLanguageCelestialPointModel = Field(title="Celestial Points", description="The celestial points translations in the chart, in the language")
+    composite_chart: str = Field(title="Composite Chart", description="The composite chart label in the chart, in the language")
+    midpoints: str = Field(title="Midpoints", description="The midpoints label in the chart, in the language")
+    north_letter: str = Field(title="North Letter", description="The north letter in the chart, in the language")
+    east_letter: str = Field(title="East Letter", description="The east letter in the chart, in the language")
+    south_letter: str = Field(title="South Letter", description="The south letter in the chart, in the language")
+    west_letter: str = Field(title="West Letter", description="The west letter in the chart, in the language")
+    tropical: str = Field(title="Tropical", description="The tropical zodiac label in the chart, in the language")
+    sidereal: str = Field(title="Sidereal", description="The sidereal zodiac label in the chart, in the language")
+    zodiac: str = Field(title="Zodiac", description="The zodiac label in the chart, in the language")
+    ayanamsa: str = Field(title="Ayanamsa", description="The ayanamsa label in the chart, in the language")
+    apparent_geocentric: str = Field(title="Apparent Geocentric", description="The apparent geocentric label in the chart, in the language")
+    heliocentric: str = Field(title="Heliocentric", description="The heliocentric label in the chart, in the language")
+    topocentric: str = Field(title="Topocentric", description="The topocentric label in the chart, in the language")
+    true_geocentric: str = Field(title="True Geocentric", description="The true geocentric label in the chart, in the language")
+    new_moon: str = Field(title="New Moon", description="The new moon label in the chart, in the language")
+    waxing_crescent: str = Field(title="Waxing Crescent", description="The waxing crescent label in the chart, in the language")
+    first_quarter: str = Field(title="First Quarter", description="The first quarter label in the chart, in the language")
+    waxing_gibbous: str = Field(title="Waxing Gibbous", description="The waxing gibbous label in the chart, in the language")
+    full_moon: str = Field(title="Full Moon", description="The full moon label in the chart, in the language")
+    waning_gibbous: str = Field(title="Waning Gibbous", description="The waning gibbous label in the chart, in the language")
+    last_quarter: str = Field(title="Last Quarter", description="The last quarter label in the chart, in the language")
+    waning_crescent: str = Field(title="Waning Crescent", description="The waning crescent label in the chart, in the language")
+    houses: str = Field(title="Houses", description="The houses label in the chart, in the language")
+    domification: str = Field(title="Domification", description="The domification label in the chart, in the language")
+    houses_system_A: str = Field(title="Houses System A", description="The houses system A label in the chart, in the language")
+    houses_system_B: str = Field(title="Houses System B", description="The houses system B label in the chart, in the language")
+    houses_system_C: str = Field(title="Houses System C", description="The houses system C label in the chart, in the language")
+    houses_system_D: str = Field(title="Houses System D", description="The houses system D label in the chart, in the language")
+    houses_system_F: str = Field(title="Houses System F", description="The houses system F label in the chart, in the language")
+    houses_system_H: str = Field(title="Houses System H", description="The houses system H label in the chart, in the language")
+    houses_system_I: str = Field(title="Houses System I", description="The houses system I label in the chart, in the language")
+    houses_system_i: str = Field(title="Houses System i", description="The houses system i label in the chart, in the language")
+    houses_system_K: str = Field(title="Houses System K", description="The houses system K label in the chart, in the language")
+    houses_system_L: str = Field(title="Houses System L", description="The houses system L label in the chart, in the language")
+    houses_system_M: str = Field(title="Houses System M", description="The houses system M label in the chart, in the language")
+    houses_system_N: str = Field(title="Houses System N", description="The houses system N label in the chart, in the language")
+    houses_system_O: str = Field(title="Houses System O", description="The houses system O label in the chart, in the language")
+    houses_system_P: str = Field(title="Houses System P", description="The houses system P label in the chart, in the language")
+    houses_system_Q: str = Field(title="Houses System Q", description="The houses system Q label in the chart, in the language")
+    houses_system_R: str = Field(title="Houses System R", description="The houses system R label in the chart, in the language")
+    houses_system_S: str = Field(title="Houses System S", description="The houses system S label in the chart, in the language")
+    houses_system_T: str = Field(title="Houses System T", description="The houses system T label in the chart, in the language")
+    houses_system_U: str = Field(title="Houses System U", description="The houses system U label in the chart, in the language")
+    houses_system_V: str = Field(title="Houses System V", description="The houses system V label in the chart, in the language")
+    houses_system_W: str = Field(title="Houses System W", description="The houses system W label in the chart, in the language")
+    houses_system_X: str = Field(title="Houses System X", description="The houses system X label in the chart, in the language")
+    houses_system_Y: str = Field(title="Houses System Y", description="The houses system Y label in the chart, in the language")
+    Natal: str = Field(title="Natal", description="The natal chart label in the chart, in the language")
+    ExternalNatal: str = Field(title="External Natal", description="The external natal chart label in the chart, in the language")
+    Synastry: str = Field(title="Synastry", description="The synastry chart label in the chart, in the language")
+    Transit: str = Field(title="Transit", description="The transit chart label in the chart, in the language")
+    Composite: str = Field(title="Composite", description="The composite chart label in the chart, in the language")
+    Return: str = Field(title="Return", description="The return chart label in the chart, in the language")
+    return_aspects: str = Field(title="Return Aspects", description="The return aspects label in the chart, in the language")
+    solar_return: str = Field(title="Solar Return", description="The solar return label in the chart, in the language")
+    lunar_return: str = Field(title="Lunar Return", description="The lunar return label in the chart, in the language")
+    inner_wheel: str = Field(title="Inner Wheel", description="The inner wheel label in the chart, in the language")
+    outer_wheel: str = Field(title="Outer Wheel", description="The outer wheel label in the chart, in the language")
+    house_position_comparison: str = Field(title="House Position Comparison", description="The house position comparison label in the chart, in the language")
+    return_point: str = Field(title="Return Point", description="The return point label in the chart, in the language")
+    natal: str = Field(title="Natal", description="The natal label in the chart, in the language")
+    perspective_type: str = Field(title="Perspective Type", description="The perspective type label in the chart, in the language")
 
 # Settings Model
 class KerykeionSettingsModel(SubscriptableBaseModel):
     """
     This class is used to define the global settings for the Kerykeion.
     """
-
-    chart_colors: KerykeionSettingsChartColorsModel = Field(title="Chart Colors", description="The colors of the chart")
-    celestial_points: List[KerykeionSettingsCelestialPointModel] = Field(title="Celestial Points", description="The list of the celestial points of the chart")
-    aspects: List[KerykeionSettingsAspectModel] = Field(title="Aspects", description="The list of the aspects of the chart")
     language_settings: dict[str, KerykeionLanguageModel] = Field(title="Language Settings", description="The language settings of the chart")
-    general_settings: KerykeionGeneralSettingsModel = Field(title="General Settings", description="The general settings of the chart")

kerykeion/planetary_return_factory.py

@@ -0,0 +1,299 @@
+# -*- coding: utf-8 -*-
+"""
+Module for generating Planetary Return charts using the Swiss Ephemeris.
+
+This module provides the PlanetaryReturnFactory class, which computes
+the return times and chart data for solar and lunar returns of a natal
+astrological subject.
+"""
+import logging
+import swisseph as swe
+
+from datetime import datetime, timezone
+from typing import Optional, Union
+
+from kerykeion.kr_types import KerykeionException
+from kerykeion.fetch_geonames import FetchGeonames
+from kerykeion.utilities import julian_to_datetime, datetime_to_julian
+from kerykeion.astrological_subject_factory import (
+    GEONAMES_DEFAULT_USERNAME_WARNING,
+    DEFAULT_GEONAMES_CACHE_EXPIRE_AFTER_DAYS,
+)
+from kerykeion.astrological_subject_factory import AstrologicalSubjectFactory
+from kerykeion.kr_types.kr_literals import ReturnType
+from kerykeion.kr_types.kr_models import PlanetReturnModel, AstrologicalSubjectModel
+
+
+class PlanetaryReturnFactory:
+    """
+    Calculator class to generate Solar and Lunar Return charts.
+    """
+
+    def __init__(
+            self,
+            subject: AstrologicalSubjectModel,
+            city: Union[str, None] = None,
+            nation: Union[str, None] = None,
+            lng: Union[int, float, None] = None,
+            lat: Union[int, float, None] = None,
+            tz_str: Union[str, None] = None,
+            online: bool = True,
+            geonames_username: Union[str, None] = None,
+            *,
+            cache_expire_after_days: int = DEFAULT_GEONAMES_CACHE_EXPIRE_AFTER_DAYS,
+            altitude: Union[float, int, None] = None,
+        ):
+
+        """
+        Initialize a PlanetaryReturnFactory instance.
+
+        Args:
+            subject (AstrologicalSubject): The natal astrological subject.
+            city (Optional[str]): City name for return location (online mode).
+            nation (Optional[str]): Nation code for return location (online mode).
+            lng (Optional[Union[int, float]]): Longitude for return location.
+            lat (Optional[Union[int, float]]): Latitude for return location.
+            tz_str (Optional[str]): Timezone string for return location.
+            online (bool): Whether to fetch location data online via Geonames.
+            geonames_username (Optional[str]): Username for Geonames API.
+            cache_expire_after_days (int): Days to expire Geonames cache.
+            altitude (Optional[float]): Altitude of the location (reserved for future use).
+        """
+        # Store basic configuration
+        self.subject = subject
+        self.online = online
+        self.cache_expire_after_days = cache_expire_after_days
+        self.altitude = altitude
+
+        # Geonames username
+        if geonames_username is None and online and (not lat or not lng or not tz_str):
+            logging.warning(GEONAMES_DEFAULT_USERNAME_WARNING)
+            self.geonames_username = DEFAULT_GEONAMES_USERNAME
+        else:
+            self.geonames_username = geonames_username # type: ignore
+
+        # City
+        if not city and online:
+            raise KerykeionException("You need to set the city if you want to use the online mode!")
+        else:
+            self.city = city
+
+        # Nation
+        if not nation and online:
+            raise KerykeionException("You need to set the nation if you want to use the online mode!")
+        else:
+            self.nation = nation
+
+        # Latitude
+        if not lat and not online:
+            raise KerykeionException("You need to set the coordinates and timezone if you want to use the offline mode!")
+        else:
+            self.lat = lat # type: ignore
+
+        # Longitude
+        if not lng and not online:
+            raise KerykeionException("You need to set the coordinates and timezone if you want to use the offline mode!")
+        else:
+            self.lng = lng # type: ignore
+
+        # Timezone
+        if (not online) and (not tz_str):
+            raise KerykeionException("You need to set the coordinates and timezone if you want to use the offline mode!")
+        else:
+            self.tz_str = tz_str # type: ignore
+
+        # Online mode
+        if (self.online) and (not self.tz_str) and (not self.lat) and (not self.lng):
+            logging.info("Fetching timezone/coordinates from geonames")
+
+            if not self.city or not self.nation or not self.geonames_username:
+                raise KerykeionException("You need to set the city and nation if you want to use the online mode!")
+
+            geonames = FetchGeonames(
+                self.city,
+                self.nation,
+                username=self.geonames_username,
+                cache_expire_after_days=self.cache_expire_after_days
+            )
+            self.city_data: dict[str, str] = geonames.get_serialized_data()
+
+            if (
+                not "countryCode" in self.city_data
+                or not "timezonestr" in self.city_data
+                or not "lat" in self.city_data
+                or not "lng" in self.city_data
+            ):
+                raise KerykeionException("No data found for this city, try again! Maybe check your connection?")
+
+            self.nation = self.city_data["countryCode"]
+            self.lng = float(self.city_data["lng"])
+            self.lat = float(self.city_data["lat"])
+            self.tz_str = self.city_data["timezonestr"]
+
+    def next_return_from_iso_formatted_time(
+        self,
+        iso_formatted_time: str,
+        return_type: ReturnType
+    ) -> PlanetReturnModel:
+        """
+        Get the next Return for the provided ISO-formatted time.
+
+        Args:
+            iso_formatted_time (str): ISO-formatted datetime string.
+
+        Returns:
+            PlanetReturnModel: Pydantic model containing the return chart data.
+        """
+
+        date = datetime.fromisoformat(iso_formatted_time)
+        julian_day = datetime_to_julian(date)
+
+        return_julian_date = None
+        if return_type == "Solar":
+            return_julian_date = swe.solcross_ut(
+                self.subject.sun.abs_pos,
+                julian_day,
+            )
+        elif return_type == "Lunar":
+            return_julian_date = swe.mooncross_ut(
+                self.subject.moon.abs_pos,
+                julian_day,
+            )
+        else:
+            raise KerykeionException(f"Invalid return type {return_type}. Use 'Solar' or 'Lunar'.")
+
+        solar_return_date_utc = julian_to_datetime(return_julian_date)
+        solar_return_date_utc = solar_return_date_utc.replace(tzinfo=timezone.utc)
+
+        solar_return_astrological_subject = AstrologicalSubjectFactory.from_iso_utc_time(
+            name=self.subject.name,
+            iso_utc_time=solar_return_date_utc.isoformat(),
+            lng=self.lng,       # type: ignore
+            lat=self.lat,       # type: ignore
+            tz_str=self.tz_str, # type: ignore
+            city=self.city,     # type: ignore
+            nation=self.nation, # type: ignore
+            online=False,
+            altitude=self.altitude,
+        )
+
+        model_data = solar_return_astrological_subject.model_dump()
+        model_data['name'] = f"{self.subject.name} {return_type} Return"
+        model_data['return_type'] = return_type
+
+        return PlanetReturnModel(
+            **model_data,
+        )
+
+    def next_return_from_year(
+        self,
+        year: int,
+        return_type: ReturnType
+    ) -> PlanetReturnModel:
+        """
+        Get the next Return for the specified year.
+
+        This method finds the first return that occurs in the given year.
+
+        Args:
+            year (int): The year to search for the return
+            return_type (ReturnType): The type of return ("Solar" or "Lunar")
+
+        Returns:
+            PlanetReturnModel: Pydantic model containing the return chart data
+        """
+        # Create datetime for January 1st of the specified year (UTC)
+        start_date = datetime(year, 1, 1, 0, 0, tzinfo=timezone.utc)
+
+        # Get the return using the existing method
+        return self.next_return_from_iso_formatted_time(
+            start_date.isoformat(),
+            return_type
+        )
+
+    def next_return_from_month_and_year(
+        self,
+        year: int,
+        month: int,
+        return_type: ReturnType
+    ) -> PlanetReturnModel:
+        """
+        Get the next Return for the specified month and year.
+
+        This method finds the first return that occurs after the first day
+        of the specified month and year.
+
+        Args:
+            year (int): The year to search for the return
+            month (int): The month to search for the return (1-12)
+            return_type (ReturnType): The type of return ("Solar" or "Lunar")
+
+        Returns:
+            PlanetReturnModel: Pydantic model containing the return chart data
+        """
+        # Validate month input
+        if month < 1 or month > 12:
+            raise KerykeionException(f"Invalid month {month}. Month must be between 1 and 12.")
+
+        # Create datetime for the first day of the specified month and year (UTC)
+        start_date = datetime(year, month, 1, 0, 0, tzinfo=timezone.utc)
+
+        # Get the return using the existing method
+        return self.next_return_from_iso_formatted_time(
+            start_date.isoformat(),
+            return_type
+        )
+
+
+if __name__ == "__main__":
+    import json
+    # Example usage
+    subject = AstrologicalSubjectFactory.from_birth_data(
+        name="Test Subject",
+        lng=-122.4194,
+        lat=37.7749,
+        tz_str="America/Los_Angeles",
+    )
+
+    print("=== Planet Return Calculator ===")
+    calculator = PlanetaryReturnFactory(
+        subject,
+        city="San Francisco",
+        nation="USA",
+        online=True,
+        geonames_username="century.boy",
+    )
+    date = datetime(2026, 1, 1, 0, 0, tzinfo=timezone.utc)
+    print(f"INITIAL DATE:                   {date.isoformat()}")
+    print(f"INITIAL DATE JULIAN:            {datetime_to_julian(date)}")
+    print(f"INITIAL DATE REVERSED:          {julian_to_datetime(datetime_to_julian(date)).isoformat()}")
+    solar_return = calculator.next_return_from_iso_formatted_time(
+        date.isoformat(),
+        return_type="Lunar",
+    )
+    print("--- After ---")
+    print(f"Solar Return Date UTC:          {solar_return.iso_formatted_utc_datetime}")
+    print(f"Solar Return Date Local:        {solar_return.iso_formatted_local_datetime}")
+    print(f"Solar Return JSON:              {json.dumps(solar_return.model_dump(), indent=4)}")
+    print(f"Solar Return Julian Data:       {solar_return.julian_day}")
+    print(f"ISO UTC:                        {solar_return.iso_formatted_utc_datetime}")
+
+    ## From Year
+    print("=== Planet Return Calculator ===")
+    solar_return = calculator.next_return_from_year(
+        2026,
+        return_type="Lunar",
+    )
+    print("--- From Year ---")
+    print(f"Solar Return Julian Data:       {solar_return.julian_day}")
+    print(f"Solar Return Date UTC:          {solar_return.iso_formatted_utc_datetime}")
+    ## From Month and Year
+    print("=== Planet Return Calculator ===")
+    solar_return = calculator.next_return_from_month_and_year(
+        2026,
+        1,
+        return_type="Lunar",
+    )
+    print("--- From Month and Year ---")
+    print(f"Solar Return Julian Data:       {solar_return.julian_day}")
+    print(f"Solar Return Date UTC:          {solar_return.iso_formatted_utc_datetime}")

kerykeion/relationship_score/relationship_score.py

@@ -3,7 +3,7 @@
     This is part of Kerykeion (C) 2025 Giacomo Battaglia
 """
 
-from kerykeion import AstrologicalSubject
+from kerykeion import AstrologicalSubjectFactory
 from kerykeion.aspects.synastry_aspects import SynastryAspects
 import logging
 from pathlib import Path
@@ -33,8 +33,8 @@ class RelationshipScore:
 
     def __init__(
         self,
-        first_subject: Union[AstrologicalSubject, AstrologicalSubjectModel],
-        second_subject: Union[AstrologicalSubject, AstrologicalSubjectModel],
+        first_subject: AstrologicalSubjectModel,
+        second_subject: AstrologicalSubjectModel,
         new_settings_file: Union[Path, None] = None,
     ):
         warnings.warn(

kerykeion/relationship_score/relationship_score_factory.py

@@ -3,7 +3,7 @@
     This is part of Kerykeion (C) 2025 Giacomo Battaglia
 """
 
-from kerykeion import AstrologicalSubject
+from kerykeion import AstrologicalSubjectFactory
 from kerykeion.aspects.synastry_aspects import SynastryAspects
 import logging
 from pathlib import Path
@@ -27,8 +27,8 @@ class RelationshipScoreFactory:
     Documentation: http://www.cirodiscepolo.it/Articoli/Discepoloele.htm
 
     Args:
-        first_subject (Union[AstrologicalSubject, AstrologicalSubjectModel]): First subject instance
-        second_subject (Union[AstrologicalSubject, AstrologicalSubjectModel]): Second subject instance
+        first_subject (AstrologicalSubjectModel): First subject instance
+        second_subject (AstrologicalSubjectModel): Second subject instance
     """
 
     SCORE_MAPPING = [
@@ -44,16 +44,13 @@ class RelationshipScoreFactory:
 
     def __init__(
         self,
-        first_subject: Union[AstrologicalSubject, AstrologicalSubjectModel],
-        second_subject: Union[AstrologicalSubject, AstrologicalSubjectModel],
+        first_subject: AstrologicalSubjectModel,
+        second_subject: AstrologicalSubjectModel,
         use_only_major_aspects: bool = True,
     ):
-        if isinstance(first_subject, AstrologicalSubject):
-            self.first_subject = first_subject.model()
-        if isinstance(second_subject, AstrologicalSubject):
-            self.second_subject = second_subject.model()
-
         self.use_only_major_aspects = use_only_major_aspects
+        self.first_subject: AstrologicalSubjectModel = first_subject
+        self.second_subject: AstrologicalSubjectModel = second_subject
 
         self.score_value = 0
         self.relationship_score_description: RelationshipScoreDescription = "Minimal"
@@ -221,8 +218,8 @@ if __name__ == "__main__":
 
     setup_logging(level="critical")
 
-    giacomo = AstrologicalSubject("Giacomo", 1993, 6, 10, 12, 15, "Montichiari", "IT")
-    yoko = AstrologicalSubject("Susie Cox", 1949, 6, 17, 9, 40, "Tucson", "US")
+    giacomo = AstrologicalSubjectFactory.from_birth_data("Giacomo", 1993, 6, 10, 12, 15, "Montichiari", "IT")
+    yoko = AstrologicalSubjectFactory.from_birth_data("Susie Cox", 1949, 6, 17, 9, 40, "Tucson", "US")
 
     factory = RelationshipScoreFactory(giacomo, yoko)
     score = factory.get_relationship_score()