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

kerykeion/kr_types/chart_types.py

@@ -20,6 +20,7 @@ class ChartTemplateDictionary(TypedDict):
     viewbox: str
     stringTitle: str
     stringName: str
+    bottomLeft0: str
     bottomLeft1: str
     bottomLeft2: str
     bottomLeft3: 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"]
+"""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,43 +4,15 @@
 """
 
 
-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
 
+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)
 
@@ -53,8 +25,15 @@ class LunarPhaseModel(BaseModel):
     def get(self, key, default):
         return getattr(self, key, default)
 
+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(BaseModel):
+class KerykeionPointModel(SubscriptableBaseModel):
     """
     Kerykeion Point Model
     """
@@ -63,52 +42,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[HouseNumbers] = 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,8 +65,12 @@ 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
 
     # Planets
@@ -137,6 +84,8 @@ class AstrologicalSubjectModel(BaseModel):
     uranus: KerykeionPointModel
     neptune: KerykeionPointModel
     pluto: KerykeionPointModel
+
+    # Optional Planets:
     chiron: Union[KerykeionPointModel, None]
 
     # Houses
@@ -160,6 +109,15 @@ class AstrologicalSubjectModel(BaseModel):
     # Lunar Phase
     lunar_phase: LunarPhaseModel
 
+    # Deprecated properties
+    utc_time: float
+    local_time: float
+
+    # Lists
+    # houses_list: list[KerykeionPointModel]
+    # planets_list: list[KerykeionPointModel]
+    # planets_degrees_ut: list[float]
+    # houses_degree_ut: list[float]
 
 if __name__ == "__main__":
     from kerykeion.utilities import setup_logging

kerykeion/kr_types/settings_models.py

@@ -4,29 +4,12 @@
 """
 
 
-from pydantic import BaseModel, Field
+from pydantic import Field
 from typing import List
+from kerykeion.kr_types.kr_models import SubscriptableBaseModel
 
 
-class CustomBaseModel(BaseModel):
-    """
-    Extends the BaseModel class of Pydantic to add some useful methods.
-    """
-
-    def __init__(self, **data):
-        super().__init__(**data)
-
-    def __getitem__(self, item):
-        return getattr(self, item)
-    
-    def __str__(self) -> str:
-        return str(self.model_dump())
-
-    def get(self, item, default=None):
-        return getattr(self, item, default)
-
-
-class KerykeionSettingsCelestialPointModel(CustomBaseModel):
+class KerykeionSettingsCelestialPointModel(SubscriptableBaseModel):
     """
     Defines the model for a celestial point data.
     """
@@ -41,7 +24,7 @@ class KerykeionSettingsCelestialPointModel(CustomBaseModel):
 
 
 # Chart Colors Settings
-class KerykeionSettingsChartColorsModel(CustomBaseModel):
+class KerykeionSettingsChartColorsModel(SubscriptableBaseModel):
     """
     Defines the model for the chart colors.
     """
@@ -87,7 +70,7 @@ class KerykeionSettingsChartColorsModel(CustomBaseModel):
 
 
 # Aspect Settings
-class KerykeionSettingsAspectModel(CustomBaseModel):
+class KerykeionSettingsAspectModel(SubscriptableBaseModel):
     """
     Defines the model for an aspect.
     """
@@ -103,7 +86,7 @@ class KerykeionSettingsAspectModel(CustomBaseModel):
 
 
 # Language Settings
-class KerykeionLanguageCelestialPointModel(CustomBaseModel):
+class KerykeionLanguageCelestialPointModel(SubscriptableBaseModel):
     """
     This class is used to define the labels, show in the chart, for the celestial points.
     It is used to translate the celestial points in the language of the chart.
@@ -128,7 +111,7 @@ class KerykeionLanguageCelestialPointModel(CustomBaseModel):
     Ic: str = Field(title="Imum Coeli", description="The name of Imum Coeli in the chart, in the language")
 
 
-class KerykeionLanguageModel(CustomBaseModel):
+class KerykeionLanguageModel(SubscriptableBaseModel):
     """
     This model is used to store the language settings for the chart,
     it's used to translate the celestial points and the other labels
@@ -157,17 +140,17 @@ class KerykeionLanguageModel(CustomBaseModel):
     celestial_points: KerykeionLanguageCelestialPointModel
 
 
-class KerykeionGeneralSettingsModel(CustomBaseModel):
+class KerykeionGeneralSettingsModel(SubscriptableBaseModel):
     axes_orbit: int = Field(title="Axes Orbit", description="The orbit of the axes in the chart")
     planet_in_zodiac_extra_points: int = Field(title="Planet in Zodiac Extra Points", description="The extra points of the planet in the zodiac")
     language: str = Field(title="Language", description="The language of the chart")
 
-class KerykeionChartSettingsModel(CustomBaseModel):
+class KerykeionChartSettingsModel(SubscriptableBaseModel):
     basic_chart_viewBox: str = Field(title="Basic Chart ViewBox", description="The viewbox of the basic chart")
     wide_chart_viewBox: str = Field(title="Wide Chart ViewBox", description="The viewbox of the wide chart")
 
 # Settings Model
-class KerykeionSettingsModel(CustomBaseModel):
+class KerykeionSettingsModel(SubscriptableBaseModel):
     """
     This class is used to define the global settings for the Kerykeion.
     """

kerykeion/utilities.py

@@ -1,47 +1,46 @@
 from kerykeion.kr_types import KerykeionPointModel, KerykeionException, KerykeionSettingsModel, AstrologicalSubjectModel
-from kerykeion.kr_types.kr_literals import LunarPhaseEmoji, LunarPhaseName
-from typing import Union, Literal
+from kerykeion.kr_types.kr_literals import LunarPhaseEmoji, LunarPhaseName, PointType, Planet
+from typing import Union
 import logging
 import math
 
 
 
-def get_number_from_name(name: str) -> int:
+def get_number_from_name(name: Planet) -> int:
     """Utility function, gets planet id from the name."""
-    name = name.lower()
 
-    if name == "sun":
+    if name == "Sun":
         return 0
-    elif name == "moon":
+    elif name == "Moon":
         return 1
-    elif name == "mercury":
+    elif name == "Mercury":
         return 2
-    elif name == "venus":
+    elif name == "Venus":
         return 3
-    elif name == "mars":
+    elif name == "Mars":
         return 4
-    elif name == "jupiter":
+    elif name == "Jupiter":
         return 5
-    elif name == "saturn":
+    elif name == "Saturn":
         return 6
-    elif name == "uranus":
+    elif name == "Uranus":
         return 7
-    elif name == "neptune":
+    elif name == "Neptune":
         return 8
-    elif name == "pluto":
+    elif name == "Pluto":
         return 9
-    elif name == "mean_node":
+    elif name == "Mean_Node":
         return 10
-    elif name == "true_node":
+    elif name == "True_Node":
         return 11
-    elif name == "chiron":
+    elif name == "Chiron":
         return 15
     else:
-        return int(name)
+        raise KerykeionException(f"Error in getting number from name! Name: {name}")
 
 
 def calculate_position(
-    degree: Union[int, float], number_name: str, point_type: Literal["Planet", "House"]
+    degree: Union[int, float], number_name: str, point_type: PointType
 ) -> KerykeionPointModel:
     """Utility function to create a dictionary dividing the houses or the planets list."""
 
@@ -214,14 +213,14 @@ def setup_logging(level: str) -> None:
     Args:
         level: Log level as a string, options: debug, info, warning, error
     """
-    logopt: dict[str, int] = {
+    logging_options: dict[str, int] = {
         "debug": logging.DEBUG,
         "info": logging.INFO,
         "warning": logging.WARNING,
         "error": logging.ERROR,
     }
     format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-    loglevel: int = logopt.get(level, logging.INFO)
+    loglevel: int = logging_options.get(level, logging.INFO)
     logging.basicConfig(format=format, level=loglevel)
 
 def check_if_point_between(
@@ -286,7 +285,7 @@ def get_planet_house(planet_position_degree: Union[int, float], houses_degree_ut
     elif check_if_point_between(houses_degree_ut_list[11], houses_degree_ut_list[0], planet_position_degree) == True:
         house = "Twelfth_House"
     else:
-        raise ValueError("Error in house calculation, planet: ", planet_position_degree)
+        raise ValueError("Error in house calculation, planet: ", planet_position_degree, "houses: ", houses_degree_ut_list)
 
     return house
 
@@ -354,4 +353,18 @@ def get_moon_phase_name_from_phase_int(phase: int) -> LunarPhaseName:
     else:
         raise KerykeionException(f"Error in moon name calculation! Phase: {phase}")
     
-    return result
+    return result
+
+
+def check_and_adjust_polar_latitude(latitude: float, longitude: float) -> bool:
+    """
+        Utility function to check if the location is in the polar circle.
+        If it is, it sets the latitude to 66 or -66 degrees.
+    """
+    if latitude > 66.0:
+        latitude = 66.0
+        logging.info("Polar circle override for houses, using 66 degrees")
+
+    elif latitude < -66.0:
+        latitude = -66.0
+        logging.info("Polar circle override for houses, using -66 degrees")