kerykeion.kr_types.kr_models

  1# -*- coding: utf-8 -*-
  2"""
  3    This is part of Kerykeion (C) 2025 Giacomo Battaglia
  4"""
  5
  6
  7from typing import Union, Optional
  8from typing_extensions import TypedDict
  9from pydantic import BaseModel
 10from kerykeion.kr_types.kr_literals import AspectName
 11
 12from kerykeion.kr_types import (
 13    AxialCusps,
 14    LunarPhaseEmoji,
 15    LunarPhaseName,
 16    Planet,
 17    Houses,
 18    Quality,
 19    Element,
 20    Sign,
 21    ZodiacType,
 22    SignNumbers,
 23    PointType,
 24    SiderealMode,
 25    HousesSystemIdentifier,
 26    Houses,
 27    SignsEmoji,
 28    RelationshipScoreDescription,
 29    PerspectiveType
 30)
 31
 32
 33class SubscriptableBaseModel(BaseModel):
 34    """
 35    Pydantic BaseModel with subscriptable support, so you can access the fields as if they were a dictionary.
 36    """
 37
 38    def __getitem__(self, key):
 39        return getattr(self, key)
 40
 41    def __setitem__(self, key, value):
 42        setattr(self, key, value)
 43
 44    def __delitem__(self, key):
 45        delattr(self, key)
 46
 47    def get(self, key, default = None):
 48        return getattr(self, key, default)
 49
 50
 51class LunarPhaseModel(SubscriptableBaseModel):
 52    degrees_between_s_m: Union[float, int]
 53    moon_phase: int
 54    sun_phase: int
 55    moon_emoji: LunarPhaseEmoji
 56    moon_phase_name: LunarPhaseName
 57
 58
 59class KerykeionPointModel(SubscriptableBaseModel):
 60    """
 61    Kerykeion Point Model
 62    """
 63
 64    name: Union[Planet, Houses, AxialCusps]
 65    quality: Quality
 66    element: Element
 67    sign: Sign
 68    sign_num: SignNumbers
 69    position: float
 70    abs_pos: float
 71    emoji: str
 72    point_type: PointType
 73    house: Optional[Houses] = None
 74    retrograde: Optional[bool] = None
 75
 76
 77class AstrologicalSubjectModel(SubscriptableBaseModel):
 78    """
 79    Pydantic Model for Astrological Subject
 80    """
 81
 82    # Data
 83    name: str
 84    year: int
 85    month: int
 86    day: int
 87    hour: int
 88    minute: int
 89    city: str
 90    nation: str
 91    lng: float
 92    lat: float
 93    tz_str: str
 94    zodiac_type: ZodiacType
 95    sidereal_mode: Union[SiderealMode, None]
 96    houses_system_identifier: HousesSystemIdentifier
 97    houses_system_name: str
 98    perspective_type: PerspectiveType
 99    iso_formatted_local_datetime: str
100    iso_formatted_utc_datetime: str
101    julian_day: float
102
103    # Deprecated properties -->
104    utc_time: float
105    local_time: float
106    # <-- Deprecated properties
107
108
109    # Planets
110    sun: KerykeionPointModel
111    moon: KerykeionPointModel
112    mercury: KerykeionPointModel
113    venus: KerykeionPointModel
114    mars: KerykeionPointModel
115    jupiter: KerykeionPointModel
116    saturn: KerykeionPointModel
117    uranus: KerykeionPointModel
118    neptune: KerykeionPointModel
119    pluto: KerykeionPointModel
120
121    # Axes
122    ascendant: KerykeionPointModel
123    descendant: KerykeionPointModel
124    medium_coeli: KerykeionPointModel
125    imum_coeli: KerykeionPointModel
126
127    # Optional Planets:
128    chiron: Union[KerykeionPointModel, None]
129    mean_lilith: Union[KerykeionPointModel, None]
130
131    # Houses
132    first_house: KerykeionPointModel
133    second_house: KerykeionPointModel
134    third_house: KerykeionPointModel
135    fourth_house: KerykeionPointModel
136    fifth_house: KerykeionPointModel
137    sixth_house: KerykeionPointModel
138    seventh_house: KerykeionPointModel
139    eighth_house: KerykeionPointModel
140    ninth_house: KerykeionPointModel
141    tenth_house: KerykeionPointModel
142    eleventh_house: KerykeionPointModel
143    twelfth_house: KerykeionPointModel
144
145    # Nodes
146    mean_node: KerykeionPointModel
147    true_node: KerykeionPointModel
148    mean_south_node: KerykeionPointModel
149    true_south_node: KerykeionPointModel
150
151    planets_names_list: list[Planet]
152    """Ordered list of available planets names"""
153
154    axial_cusps_names_list: list[AxialCusps]
155    """Ordered list of available axes names"""
156
157    houses_names_list: list[Houses]
158    """Ordered list of houses names"""
159
160    lunar_phase: LunarPhaseModel
161    """Lunar phase model"""
162
163
164class EphemerisDictModel(SubscriptableBaseModel):
165    date: str
166    planets: list[KerykeionPointModel]
167    houses: list[KerykeionPointModel]
168
169
170class AspectModel(SubscriptableBaseModel):
171    p1_name: str
172    p1_owner: str
173    p1_abs_pos: float
174    p2_name: str
175    p2_owner: str
176    p2_abs_pos: float
177    aspect: str
178    orbit: float
179    aspect_degrees: int
180    diff: float
181    p1: int
182    p2: int
183
184
185class ZodiacSignModel(SubscriptableBaseModel):
186    sign: Sign
187    quality: Quality
188    element: Element
189    emoji: SignsEmoji
190    sign_num: SignNumbers
191
192
193class RelationshipScoreAspectModel(SubscriptableBaseModel):
194    p1_name: str
195    p2_name: str
196    aspect: str
197    orbit: float
198
199
200class RelationshipScoreModel(SubscriptableBaseModel):
201    score_value: int
202    score_description: RelationshipScoreDescription
203    is_destiny_sign: bool
204    aspects: list[RelationshipScoreAspectModel]
205    subjects: list[AstrologicalSubjectModel]
206
207
208class CompositeSubjectModel(SubscriptableBaseModel):
209    """
210    Pydantic Model for Composite Subject
211    """
212
213    # Data
214    name: str
215    first_subject: AstrologicalSubjectModel
216    second_subject: AstrologicalSubjectModel
217    composite_chart_type: str
218
219    zodiac_type: ZodiacType
220    sidereal_mode: Union[SiderealMode, None]
221    houses_system_identifier: HousesSystemIdentifier
222    houses_system_name: str
223    perspective_type: PerspectiveType
224
225    # Planets
226    sun: KerykeionPointModel
227    moon: KerykeionPointModel
228    mercury: KerykeionPointModel
229    venus: KerykeionPointModel
230    mars: KerykeionPointModel
231    jupiter: KerykeionPointModel
232    saturn: KerykeionPointModel
233    uranus: KerykeionPointModel
234    neptune: KerykeionPointModel
235    pluto: KerykeionPointModel
236
237    # Axes
238    ascendant: KerykeionPointModel
239    descendant: KerykeionPointModel
240    medium_coeli: KerykeionPointModel
241    imum_coeli: KerykeionPointModel
242
243    # Optional Planets:
244    chiron: Union[KerykeionPointModel, None]
245    mean_lilith: Union[KerykeionPointModel, None]
246
247    # Houses
248    first_house: KerykeionPointModel
249    second_house: KerykeionPointModel
250    third_house: KerykeionPointModel
251    fourth_house: KerykeionPointModel
252    fifth_house: KerykeionPointModel
253    sixth_house: KerykeionPointModel
254    seventh_house: KerykeionPointModel
255    eighth_house: KerykeionPointModel
256    ninth_house: KerykeionPointModel
257    tenth_house: KerykeionPointModel
258    eleventh_house: KerykeionPointModel
259    twelfth_house: KerykeionPointModel
260
261    # Nodes
262    mean_node: KerykeionPointModel
263    true_node: KerykeionPointModel
264    mean_south_node: KerykeionPointModel
265    true_south_node: KerykeionPointModel
266
267    planets_names_list: list[Planet]
268    """Ordered list of available planets names"""
269
270    axial_cusps_names_list: list[AxialCusps]
271    """Ordered list of available axes names"""
272
273    houses_names_list: list[Houses]
274    """Ordered list of houses names"""
275
276    lunar_phase: LunarPhaseModel
277    """Lunar phase model"""
278
279
280class ActiveAspect(TypedDict):
281    name: AspectName
282    orb: int
283
284
285class TransitMomentModel(SubscriptableBaseModel):
286    """
287    Model representing a snapshot of astrological transits at a specific moment in time.
288
289    Captures all active aspects between moving celestial bodies and
290    the fixed positions in a person's natal chart at a specific date and time.
291
292    Attributes:
293        date: ISO 8601 formatted date and time of the transit moment.
294        aspects: List of astrological aspects active at this specific moment.
295    """
296
297    date: str
298    """ISO 8601 formatted date and time of the transit moment."""
299
300    aspects: list[AspectModel]
301    """List of aspects active at this specific moment."""
302
303
304class TransitsTimeRangeModel(SubscriptableBaseModel):
305    """
306    Model representing a collection of transit moments for an astrological subject.
307
308    This model holds a time series of transit snapshots, allowing analysis of
309    planetary movements and their aspects to a natal chart over a period of time.
310
311    Attributes:
312        transits: List of transit moments occurring during the specified time period.
313        subject: The astrological subject model for whom the transits are calculated.
314        dates: List of all dates in ISO 8601 format for which transits were calculated.
315    """
316
317    transits: list[TransitMomentModel]
318    """List of transit moments."""
319
320    subject: Optional[AstrologicalSubjectModel]
321    """Astrological subject data."""
322
323    dates: Optional[list[str]]
324    """ISO 8601 formatted dates of all transit moments."""