kerykeion 4.8.1__py3-none-any.whl → 4.14.2__py3-none-any.whl

kerykeion/enums.py

@@ -15,6 +15,7 @@ class Planets(Enum):
     CHIRON = "Chiron"
     TRUE_NODE = "True_Node"
     MEAN_NODE = "Mean_Node"
+    MEAN_LILITH = "Mean_Lilith"
 
 
 class Aspects(Enum):

kerykeion/ephemeris_data.py

@@ -0,0 +1,174 @@
+from kerykeion import AstrologicalSubject
+from kerykeion.astrological_subject import DEFAULT_HOUSES_SYSTEM_IDENTIFIER, DEFAULT_PERSPECTIVE_TYPE, DEFAULT_ZODIAC_TYPE
+from kerykeion.kr_types import EphemerisDictModel
+from kerykeion.kr_types import SiderealMode, HousesSystemIdentifier, PerspectiveType, ZodiacType
+from datetime import datetime, timedelta
+from typing import Literal, Union
+import logging
+
+
+class EphemerisDataFactory:
+    """
+    This class is used to generate ephemeris data for a given date range.
+
+    Parameters:
+    - start_datetime: datetime object representing the start date and time.
+    - end_datetime: datetime object representing the end date and time.
+    - step_type: string representing the step type. It can be "days", "hours", or "minutes". Default is "days".
+    - step: integer representing the step value. Default is 1.
+    - lat: float representing the latitude. Default is 51.4769 (Greenwich).
+    - lng: float representing the longitude. Default is 0.0005 (Greenwich).
+    - tz_str: string representing the timezone. Default is "Etc/UTC".
+    - is_dst: boolean representing if daylight saving time is active. Default is False.
+    - disable_chiron_and_lilith: boolean representing if Chiron and Lilith should be disabled. Default is False.
+    - zodiac_type: ZodiacType object representing the zodiac type. Default is DEFAULT_ZODIAC_TYPE.
+    - sidereal_mode: SiderealMode object representing the sidereal mode. Default is None.
+    - houses_system_identifier: HousesSystemIdentifier object representing the houses system identifier. Default is DEFAULT_HOUSES_SYSTEM_IDENTIFIER.
+    - perspective_type: PerspectiveType object representing the perspective type. Default is DEFAULT_PERSPECTIVE_TYPE.
+    - max_days: integer representing the maximum number of days.
+        Set it to None to disable the check. Default is 730.
+    - max_hours: integer representing the maximum number of hours.
+        Set it to None to disable the check. Default is 8760.
+    - max_minutes: integer representing the maximum number of minutes.
+        Set it to None to disable the check. Default is 525600.
+
+    Raises:
+    - ValueError: if the step type is invalid.
+    - ValueError: if the number of days, hours, or minutes is greater than the maximum allowed.
+    """
+
+    def __init__(
+        self,
+        start_datetime: datetime,
+        end_datetime: datetime,
+        step_type: Literal["days", "hours", "minutes"] = "days",
+        step: int = 1,
+        lat: float = 51.4769,
+        lng: float = 0.0005,
+        tz_str: str = "Etc/UTC",
+        is_dst: bool = False,
+        disable_chiron_and_lilith: bool = False,
+        zodiac_type: ZodiacType = DEFAULT_ZODIAC_TYPE,
+        sidereal_mode: Union[SiderealMode, None] = None,
+        houses_system_identifier: HousesSystemIdentifier = DEFAULT_HOUSES_SYSTEM_IDENTIFIER,
+        perspective_type: PerspectiveType = DEFAULT_PERSPECTIVE_TYPE,
+        max_days: int = 730,
+        max_hours: int = 8760,
+        max_minutes: int = 525600,
+    ):
+        self.start_datetime = start_datetime
+        self.end_datetime = end_datetime
+        self.step_type = step_type
+        self.step = step
+        self.lat = lat
+        self.lng = lng
+        self.tz_str = tz_str
+        self.is_dst = is_dst
+        self.disable_chiron_and_lilith = disable_chiron_and_lilith
+        self.zodiac_type = zodiac_type
+        self.sidereal_mode = sidereal_mode
+        self.houses_system_identifier = houses_system_identifier
+        self.perspective_type = perspective_type
+        self.max_days = max_days
+        self.max_hours = max_hours
+        self.max_minutes = max_minutes
+
+        self.dates_list = []
+        if self.step_type == "days":
+            self.dates_list = [self.start_datetime + timedelta(days=i) for i in range((self.end_datetime - self.start_datetime).days)]
+            if max_days and (len(self.dates_list) > max_days):
+                raise ValueError(f"Too many days: {len(self.dates_list)} > {self.max_days}. To prevent this error, set max_days to a higher value or reduce the date range.")
+
+        elif self.step_type == "hours":
+            self.dates_list = [self.start_datetime + timedelta(hours=i) for i in range((self.end_datetime - self.start_datetime).days * 24)]
+            if max_hours and (len(self.dates_list) > max_hours):
+                raise ValueError(f"Too many hours: {len(self.dates_list)} > {self.max_hours}. To prevent this error, set max_hours to a higher value or reduce the date range.")
+
+        elif self.step_type == "minutes":
+            self.dates_list = [self.start_datetime + timedelta(minutes=i) for i in range((self.end_datetime - self.start_datetime).days * 24 * 60)]
+            if max_minutes and (len(self.dates_list) > max_minutes):
+                raise ValueError(f"Too many minutes: {len(self.dates_list)} > {self.max_minutes}. To prevent this error, set max_minutes to a higher value or reduce the date range.")
+
+        else:
+            raise ValueError(f"Invalid step type: {self.step_type}")
+
+        if not self.dates_list:
+            raise ValueError("No dates found. Check the date range and step values.")
+
+        if len(self.dates_list) > 1000:
+            logging.warning(f"Large number of dates: {len(self.dates_list)}. The calculation may take a while.")
+
+    def get_ephemeris_data(self) -> list:
+        """
+        Generate ephemeris data for the specified date range.
+        The data is structured as a list of dictionaries, where each dictionary contains the date, planets, and houses data.
+        Eg. [{"date": "2020-01-01T00:00:00", "planets": [{...}, {...}, ...], "houses": [{...}, {...}, ...]}, ...]
+
+        Args:
+        - as_model: boolean representing if the ephemeris data should be returned as model instances. Default is False.
+        - as_dict: boolean representing if the ephemeris data should be returned as dictionaries. Default is False.
+
+        Returns:
+        - list of dictionaries representing the ephemeris data.
+        """
+        ephemeris_data_list = []
+        for date in self.dates_list:
+            subject = AstrologicalSubject(
+                year=date.year,
+                month=date.month,
+                day=date.day,
+                hour=date.hour,
+                minute=date.minute,
+                lng=self.lng,
+                lat=self.lat,
+                tz_str=self.tz_str,
+                city="Placeholder",
+                nation="Placeholder",
+                online=False,
+                disable_chiron_and_lilith=self.disable_chiron_and_lilith,
+                zodiac_type=self.zodiac_type,
+                sidereal_mode=self.sidereal_mode,
+                houses_system_identifier=self.houses_system_identifier,
+                perspective_type=self.perspective_type,
+                is_dst=self.is_dst,
+            )
+
+            ephemeris_data_list.append({"date": date.isoformat(), "planets": subject.planets_list, "houses": subject.houses_list})
+
+        return ephemeris_data_list
+
+    def get_ephemeris_data_as_model(self) -> list[EphemerisDictModel]:
+        """
+        Generate ephemeris data as model instances for the specified date range.
+        The data is structured as a list of EphemerisDictModel instances.
+
+        Returns:
+        - list of EphemerisDictModel instances representing the ephemeris data.
+        """
+        return [EphemerisDictModel(**data) for data in self.get_ephemeris_data()]
+
+
+if "__main__" == __name__:
+    start_date = datetime.fromisoformat("2020-01-01")
+    end_date = datetime.fromisoformat("2020-01-03")
+
+    factory = EphemerisDataFactory(
+        start_datetime=start_date,
+        end_datetime=end_date,
+        step_type="minutes",
+        step=1,
+        lat=37.9838,
+        lng=23.7275,
+        tz_str="Europe/Athens",
+        is_dst=False,
+        max_hours=None,
+        max_minutes=None,
+        max_days=None,
+    )
+
+    ephemeris_data = factory.get_ephemeris_data_as_model()
+    print(ephemeris_data[0])
+    print(len(ephemeris_data))
+
+    for ephe in ephemeris_data:
+        print(ephe.planets[0]["abs_pos"])

kerykeion/fetch_geonames.py

@@ -79,12 +79,11 @@ class FetchGeonames:
 
         params = {
             "q": city_name,
-            "contry": country_code,
+            "country": country_code,
             "username": self.username,
             "maxRows": 1,
             "style": "SHORT",
-            "featureClass": "A",
-            "featureClass": "P",
+            "featureClass": ["A", "P"],
         }
 
         prepared_request = Request("GET", self.base_url, params=params).prepare()

kerykeion/kr_types/chart_types.py

@@ -6,20 +6,15 @@ class ChartTemplateDictionary(TypedDict):
     degreeRing: str
     first_circle: str
     second_circle: str
-    c3: str
-    c3style: str
+    third_circle: str
     makeAspects: str
     makeAspectGrid: str
-    makePatterns: str
     chart_height: float
     chart_width: float
-    circleX: str
-    circleY: str
-    svgWidth: str
-    svgHeight: str
     viewbox: str
     stringTitle: str
     stringName: str
+    bottomLeft0: str
     bottomLeft1: str
     bottomLeft2: str
     bottomLeft3: str
@@ -41,7 +36,7 @@ class ChartTemplateDictionary(TypedDict):
     # Background color of the chart
     paper_color_1: str
     
-    # Planets colors, from 1 to 15 (0 is the Sun)
+    # Planets colors, from 0 to 16 (0 is the Sun)
     planets_color_0: str
     planets_color_1: str
     planets_color_2: str
@@ -58,6 +53,7 @@ class ChartTemplateDictionary(TypedDict):
     planets_color_13: str
     planets_color_14: str
     planets_color_15: str
+    planets_color_16: str
     
     # Zodiac colors, from 0 to 11 (0 is Aries)
     zodiac_color_0: str
@@ -86,7 +82,6 @@ class ChartTemplateDictionary(TypedDict):
     orb_color_150: str
     orb_color_180: str
 
-    cfgZoom: str
     cfgRotate: str
     cfgTranslate: str
     makeZodiac: str

kerykeion/kr_types/kr_literals.py

@@ -1,68 +1,101 @@
 # -*- coding: utf-8 -*-
 """
-    This is part of Kerykeion (C) 2024 Giacomo Battaglia
+This is part of Kerykeion (C) 2024 Giacomo Battaglia
 """
-
-
 from typing import Literal
 
-# Zodiac Types:
+
 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 Pisces (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)"""
+
+
+Planet = Literal["Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto", "Mean_Node", "True_Node", "Chiron", "Mean_Lilith"]
+"""Literal type for Planets"""
 
-# Sings:
-Sign = Literal[
-    "Ari", "Tau", "Gem", "Can", "Leo", "Vir", "Lib", "Sco", "Sag", "Cap", "Aqu", "Pis"
-]
-
-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",
-]
-
-Planet = Literal[
-    "Sun",
-    "Moon",
-    "Mercury",
-    "Venus",
-    "Mars",
-    "Jupiter",
-    "Saturn",
-    "Uranus",
-    "Neptune",
-    "Pluto",
-    "Mean_Node",
-    "True_Node",
-    "Chiron",
-]
 
 Element = Literal["Air", "Fire", "Earth", "Water"]
+"""Literal type for Elements"""
+
+
+Quality = Literal["Cardinal", "Fixed", "Mutable"]
+"""Literal type for Qualities"""
 
-Quality = Literal[
-    "Cardinal",
-    "Fixed",
-    "Mutable",
-]
 
 ChartType = Literal["Natal", "ExternalNatal", "Synastry", "Transit"]
+"""Literal type for Chart Types"""
+
+
+PointType = Literal["Planet", "House"]
+"""Literal type for Point Types"""
+
 
 LunarPhaseEmoji = Literal["🌑", "🌒", "🌓", "🌔", "🌕", "🌖", "🌗", "🌘"]
-LunarPhaseName = Literal[
-        "New Moon", 
-        "Waxing Crescent", 
-        "First Quarter", 
-        "Waxing Gibbous", 
-        "Full Moon", 
-        "Waning Gibbous", 
-        "Last Quarter", 
-        "Waning Crescent"
-    ]
+"""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"]
+"""
+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"
+"""

kerykeion/kr_types/kr_models.py

@@ -4,42 +4,31 @@
 """
 
 
-from typing import Literal, Union, Optional
+from typing import Union, Optional
 from pydantic import BaseModel
 
-from kerykeion.kr_types import LunarPhaseEmoji, LunarPhaseName, Planet, Houses, Quality, Element, Sign, ZodiacType
-
-
-class LunarPhaseModel(BaseModel):
-    degrees_between_s_m: Union[float, int]
-    moon_phase: int
-    sun_phase: int
-    moon_emoji: LunarPhaseEmoji
-    moon_phase_name: LunarPhaseName
-
-    def __str__(self):
-        return (
-            super()
-            .model_dump(
-                exclude_none=True,
-                exclude_unset=True,
-                exclude_defaults=True,
-                by_alias=False,
-            )
-            .__str__()
-        )
-
-    def __repr__(self):
-        return (
-            super()
-            .model_dump(
-                exclude_none=True,
-                exclude_unset=True,
-                exclude_defaults=True,
-                by_alias=False,
-            )
-            .__str__()
-        )
+from kerykeion.kr_types import (
+    LunarPhaseEmoji,
+    LunarPhaseName,
+    Planet,
+    Houses,
+    Quality,
+    Element,
+    Sign,
+    ZodiacType,
+    SignNumbers,
+    HouseNumbers,
+    PointType,
+    SiderealMode,
+    HousesSystemIdentifier,
+    Houses,
+)
+
+
+class SubscriptableBaseModel(BaseModel):
+    """
+    Pydantic BaseModel with subscriptable support, so you can access the fields as if they were a dictionary.
+    """
 
     def __getitem__(self, key):
         return getattr(self, key)
@@ -54,7 +43,15 @@ class LunarPhaseModel(BaseModel):
         return getattr(self, key, default)
 
 
-class KerykeionPointModel(BaseModel):
+class LunarPhaseModel(SubscriptableBaseModel):
+    degrees_between_s_m: Union[float, int]
+    moon_phase: int
+    sun_phase: int
+    moon_emoji: LunarPhaseEmoji
+    moon_phase_name: LunarPhaseName
+
+
+class KerykeionPointModel(SubscriptableBaseModel):
     """
     Kerykeion Point Model
     """
@@ -63,52 +60,16 @@ class KerykeionPointModel(BaseModel):
     quality: Quality
     element: Element
     sign: Sign
-    sign_num: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
+    sign_num: SignNumbers
     position: float
     abs_pos: float
     emoji: str
-    point_type: Literal["Planet", "House"]
-    house: Optional[Literal[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]] = None
+    point_type: PointType
+    house: Optional[Houses] = None
     retrograde: Optional[bool] = None
 
-    def __str__(self):
-        return (
-            super()
-            .model_dump(
-                exclude_none=True,
-                exclude_unset=True,
-                exclude_defaults=True,
-                by_alias=False,
-            )
-            .__str__()
-        )
-
-    def __repr__(self):
-        return (
-            super()
-            .model_dump(
-                exclude_none=True,
-                exclude_unset=True,
-                exclude_defaults=True,
-                by_alias=False,
-            )
-            .__str__()
-        )
-
-    def __getitem__(self, key):
-        return getattr(self, key)
-
-    def __setitem__(self, key, value):
-        setattr(self, key, value)
-
-    def __delitem__(self, key):
-        delattr(self, key)
-
-    def get(self, key, default):
-        return getattr(self, key, default)
-
 
-class AstrologicalSubjectModel(BaseModel):
+class AstrologicalSubjectModel(SubscriptableBaseModel):
     # Data
     name: str
     year: int
@@ -122,10 +83,19 @@ class AstrologicalSubjectModel(BaseModel):
     lat: float
     tz_str: str
     zodiac_type: ZodiacType
-    local_time: float
-    utc_time: float
+    sidereal_mode: Union[SiderealMode, None]
+    houses_system_identifier: HousesSystemIdentifier
+    houses_system_name: str
+    perspective_type: str
+    iso_formatted_local_datetime: str
+    iso_formatted_utc_datetime: str
     julian_day: float
 
+    # Deprecated properties -->
+    utc_time: float
+    local_time: float
+    # <-- Deprecated properties
+
     # Planets
     sun: KerykeionPointModel
     moon: KerykeionPointModel
@@ -137,7 +107,10 @@ class AstrologicalSubjectModel(BaseModel):
     uranus: KerykeionPointModel
     neptune: KerykeionPointModel
     pluto: KerykeionPointModel
+
+    # Optional Planets:
     chiron: Union[KerykeionPointModel, None]
+    mean_lilith: Union[KerykeionPointModel, None]
 
     # Houses
     first_house: KerykeionPointModel
@@ -160,23 +133,28 @@ class AstrologicalSubjectModel(BaseModel):
     # Lunar Phase
     lunar_phase: LunarPhaseModel
 
-
-if __name__ == "__main__":
-    from kerykeion.utilities import setup_logging
-
-    setup_logging(level="debug")
-
-    sun = KerykeionPointModel(
-        name="Sun",
-        element="Air",
-        quality="Fixed",
-        sign="Aqu",
-        sign_num=1,
-        position=0,
-        abs_pos=12.123123,
-        emoji="♈",
-        point_type="Planet",
-    )
-
-    print(sun.model_dump_json())
-    print(sun)
+    # Lists
+    # houses_list: list[KerykeionPointModel]
+    # planets_list: list[KerykeionPointModel]
+    # planets_degrees_ut: list[float]
+    # houses_degree_ut: list[float]
+
+
+class EphemerisDictModel(SubscriptableBaseModel):
+    date: str
+    planets: list[KerykeionPointModel]
+    houses: list[KerykeionPointModel]
+
+
+class AspectModel(SubscriptableBaseModel):
+    p1_name: str
+    p1_abs_pos: float
+    p2_name: str
+    p2_abs_pos: float
+    aspect: str
+    orbit: float
+    aspect_degrees: int
+    aid: int
+    diff: float
+    p1: int
+    p2: int