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

kerykeion/astrological_subject.py

@@ -6,8 +6,10 @@
 import pytz
 import swisseph as swe
 import logging
+import warnings
 
 from datetime import datetime
+from functools import cached_property
 from kerykeion.fetch_geonames import FetchGeonames
 from kerykeion.kr_types import (
     KerykeionException,
@@ -15,6 +17,10 @@ from kerykeion.kr_types import (
     AstrologicalSubjectModel,
     LunarPhaseModel,
     KerykeionPointModel,
+    PointType,
+    SiderealMode,
+    HousesSystemIdentifier,
+    PerspectiveType
 )
 from kerykeion.utilities import (
     get_number_from_name, 
@@ -22,11 +28,27 @@ from kerykeion.utilities import (
     get_planet_house,
     get_moon_emoji_from_phase_int,
     get_moon_phase_name_from_phase_int,
+    check_and_adjust_polar_latitude
 )
 from pathlib import Path
-from typing import Union, Literal
+from typing import Union, get_args
 
 DEFAULT_GEONAMES_USERNAME = "century.boy"
+DEFAULT_SIDEREAL_MODE = "FAGAN_BRADLEY"
+DEFAULT_HOUSES_SYSTEM_IDENTIFIER = "P"
+DEFAULT_ZODIAC_TYPE = "Tropic"
+DEFAULT_PERSPECTIVE_TYPE = "Apparent Geocentric"
+GEONAMES_DEFAULT_USERNAME_WARNING = (
+    "\n********\n"
+    "NO GEONAMES USERNAME SET!\n"
+    "Using the default geonames username is not recommended, please set a custom one!\n"
+    "You can get one for free here:\n"
+    "https://www.geonames.org/login\n"
+    "Keep in mind that the default username is limited to 2000 requests per hour and is shared with everyone else using this library.\n"
+    "********"
+)
+
+NOW = datetime.now()
 
 
 class AstrologicalSubject:
@@ -35,55 +57,70 @@ class AstrologicalSubject:
     it's utc and julian day and returns an object with all that data.
 
     Args:
-    - name (str, optional): _ Defaults to "Now".
-    - year (int, optional): _ Defaults to now.year.
-    - month (int, optional): _ Defaults to now.month.
-    - day (int, optional): _ Defaults to now.day.
-    - hour (int, optional): _ Defaults to now.hour.
-    - minute (int, optional): _ Defaults to now.minute.
+    - name (str, optional): The name of the subject. Defaults to "Now".
+    - year (int, optional): The year of birth. Defaults to the current year.
+    - month (int, optional): The month of birth. Defaults to the current month.
+    - day (int, optional): The day of birth. Defaults to the current day.
+    - hour (int, optional): The hour of birth. Defaults to the current hour.
+    - minute (int, optional): Defaults to the current minute.
     - city (str, optional): City or location of birth. Defaults to "London", which is GMT time.
         The city argument is used to get the coordinates and timezone from geonames just in case
         you don't insert them manually (see _get_tz).
         If you insert the coordinates and timezone manually, the city argument is not used for calculations
         but it's still used as a value for the city attribute.
     - nat (str, optional): _ Defaults to "".
-    - lng (Union[int, float], optional): _ Defaults to False.
-    - lat (Union[int, float], optional): _ Defaults to False.
-    - tz_str (Union[str, bool], optional): _ Defaults to False.
-    - geonames_username (str, optional): _ Defaults to 'century.boy'.
-    - online (bool, optional): Sets if you want to use the online mode (using
-        geonames) or not. Defaults to True.
-    - utc_datetime (datetime, optional): An alternative way of constructing the object, 
-        if you know the UTC datetime but do not have easy access to e.g. timezone identifier
-        _ Defaults to None.
-    - disable_chiron (bool, optional): Disables the calculation of Chiron. Defaults to False.
+    - lng (Union[int, float], optional): Longitude of the birth location. Defaults to 0 (Greenwich, London).
+    - lat (Union[int, float], optional): Latitude of the birth location. Defaults to 51.5074 (Greenwich, London).
+    - tz_str (Union[str, bool], optional): Timezone of the birth location. Defaults to "GMT".
+    - geonames_username (str, optional): The username for the geonames API. Note: Change this to your own username to avoid rate limits!
+        You can get one for free here: https://www.geonames.org/login
+    - online (bool, optional): Sets if you want to use the online mode, which fetches the timezone and coordinates from geonames.
+        If you already have the coordinates and timezone, set this to False. Defaults to True.
+    - disable_chiron: Deprecated, use disable_chiron_and_lilith instead.
+    - sidereal_mode (SiderealMode, optional): Also known as Ayanamsa. 
+        The mode to use for the sidereal zodiac, according to the Swiss Ephemeris.
+        Defaults to "FAGAN_BRADLEY".
+        Available modes are visible in the SiderealMode Literal.
+    - houses_system_identifier (HousesSystemIdentifier, optional): The system to use for the calculation of the houses.
+        Defaults to "P" (Placidus).
+        Available systems are visible in the HousesSystemIdentifier Literal.
+    - perspective_type (PerspectiveType, optional): The perspective to use for the calculation of the chart.
+        Defaults to "Apparent Geocentric".
+        Available perspectives are visible in the PerspectiveType Literal.
+    - is_dst (Union[None, bool], optional): Specify if the time is in DST. Defaults to None.
+        By default (None), the library will try to guess if the time is in DST or not and raise an AmbiguousTimeError
+        if it can't guess. If you know the time is in DST, set this to True, if you know it's not, set it to False.
+    - disable_chiron_and_lilith (bool, optional): boolean representing if Chiron and Lilith should be disabled. Default is False.
         Chiron calculation can create some issues with the Swiss Ephemeris when the date is too far in the past.
     """
 
     # Defined by the user
     name: str
-    utc_datetime: Union[datetime, None]
     year: int
     month: int
     day: int
     hour: int
     minute: int
-    city: str
-    nation: str
-    lng: Union[int, float]
-    lat: Union[int, float]
-    tz_str: str
-    geonames_username: str
+    city: Union[str, None]
+    nation: Union[str, None]
+    lng: Union[int, float, None]
+    lat: Union[int, float, None]
+    tz_str: Union[str, None]
+    geonames_username: Union[str, None]
     online: bool
     zodiac_type: ZodiacType
+    sidereal_mode: Union[SiderealMode, None]
+    houses_system_identifier: HousesSystemIdentifier
+    houses_system_name: str
+    perspective_type: PerspectiveType
+    is_dst: Union[None, bool]
 
     # Generated internally
     city_data: dict[str, str]
     julian_day: Union[int, float]
-    utc_time: float
-    local_time: float
-    utc: datetime
     json_dir: Path
+    iso_formatted_local_datetime: str
+    iso_formatted_utc_datetime: str
 
     # Planets
     sun: KerykeionPointModel
@@ -99,6 +136,7 @@ class AstrologicalSubject:
     true_node: KerykeionPointModel
     mean_node: KerykeionPointModel
     chiron: Union[KerykeionPointModel, None]
+    mean_lilit: Union[KerykeionPointModel, None]
 
     # Houses
     first_house: KerykeionPointModel
@@ -120,35 +158,48 @@ class AstrologicalSubject:
     planets_degrees_ut: list[float]
     houses_degree_ut: list[float]
 
-    now = datetime.now()
+    # Enable or disable features
+    disable_chiron: bool # Deprecated
+    disable_chiron_and_lilith: bool
 
     def __init__(
         self,
         name="Now",
-        year: int = now.year,
-        month: int = now.month,
-        day: int = now.day,
-        hour: int = now.hour,
-        minute: int = now.minute,
+        year: int = NOW.year,
+        month: int = NOW.month,
+        day: int = NOW.day,
+        hour: int = NOW.hour,
+        minute: int = NOW.minute,
         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,
         geonames_username: Union[str, None] = None,
-        zodiac_type: ZodiacType = "Tropic",
+        zodiac_type: ZodiacType = DEFAULT_ZODIAC_TYPE,
         online: bool = True,
-        utc_datetime: Union[datetime, None] = None,
-        disable_chiron: bool = False
+        disable_chiron: Union[None, bool] = None,
+        sidereal_mode: Union[SiderealMode, None] = None,
+        houses_system_identifier: HousesSystemIdentifier = DEFAULT_HOUSES_SYSTEM_IDENTIFIER,
+        perspective_type: PerspectiveType = DEFAULT_PERSPECTIVE_TYPE,
+        is_dst: Union[None, bool] = None,
+        disable_chiron_and_lilith: bool = False
     ) -> None:
         logging.debug("Starting Kerykeion")
 
-        # We set the swisseph path to the current directory
-        swe.set_ephe_path(
-            str(
-                Path(__file__).parent.absolute() / "sweph"
+        # Deprecation warnings --->
+        if disable_chiron is not None:
+            warnings.warn(
+                "The 'disable_chiron' argument is deprecated and will be removed in a future version. "
+                "Please use 'disable_chiron' instead.",
+                DeprecationWarning
             )
-        )
+            
+            if disable_chiron_and_lilith:
+                raise ValueError("Cannot specify both 'disable_chiron' and 'disable_chiron_and_lilith'. Use 'disable_chiron_and_lilith' only.")
+        
+            self.disable_chiron_and_lilith = disable_chiron
+        # <--- Deprecation warnings
 
         self.name = name
         self.year = year
@@ -165,27 +216,20 @@ class AstrologicalSubject:
         self.online = online
         self.json_dir = Path.home()
         self.geonames_username = geonames_username
-        self.utc_datetime = utc_datetime
         self.disable_chiron = disable_chiron
+        self.sidereal_mode = sidereal_mode
+        self.houses_system_identifier = houses_system_identifier
+        self.perspective_type = perspective_type
+        self.is_dst = is_dst
+        self.disable_chiron_and_lilith = disable_chiron_and_lilith
+
+        #---------------#
+        # General setup #
+        #---------------#
 
         # This message is set to encourage the user to set a custom geonames username
         if geonames_username is None and online:
-            logging.warning(
-                "\n"
-                "********" +
-                "\n" +
-                "NO GEONAMES USERNAME SET!" +
-                "\n" +
-                "Using the default geonames username is not recommended, please set a custom one!" +
-                "\n" +
-                "You can get one for free here:" +
-                "\n" +
-                "https://www.geonames.org/login" +
-                "\n" +
-                "Keep in mind that the default username is limited to 2000 requests per hour and is shared with everyone else using this library." +
-                "\n" +
-                "********"
-            )
+            logging.warning(GEONAMES_DEFAULT_USERNAME_WARNING)
 
             self.geonames_username = DEFAULT_GEONAMES_USERNAME
 
@@ -197,36 +241,117 @@ class AstrologicalSubject:
             self.nation = "GB"
             logging.info("No nation specified, using GB as default")
 
-        if not self.lat:
+        if not self.lat and not self.online:
             self.lat = 51.5074
             logging.info("No latitude specified, using London as default")
 
-        if not self.lng:
+        if not self.lng and not self.online:
             self.lng = 0
             logging.info("No longitude specified, using London as default")
 
         if (not self.online) and (not tz_str):
-            raise KerykeionException(
-                "You need to set the coordinates and timezone if you want to use the offline mode!"
-            )
+            raise KerykeionException("You need to set the coordinates and timezone if you want to use the offline mode!")
+
+        #-----------------------#
+        # Swiss Ephemeris setup #
+        #-----------------------#
+
+        # We set the swisseph path to the current directory
+        swe.set_ephe_path(str(Path(__file__).parent.absolute() / "sweph"))
 
-        self._check_if_poles()
+        # Flags for the Swiss Ephemeris
+        self._iflag = swe.FLG_SWIEPH + swe.FLG_SPEED
+
+        # Chart Perspective check and setup --->
+        if self.perspective_type not in get_args(PerspectiveType):
+            raise KerykeionException(f"\n* ERROR: '{self.perspective_type}' is NOT a valid chart perspective! Available perspectives are: *" + "\n" + str(get_args(PerspectiveType)))
+        
+        if self.perspective_type == "True Geocentric":
+            self._iflag += swe.FLG_TRUEPOS
+        elif self.perspective_type == "Heliocentric":
+            self._iflag += swe.FLG_HELCTR
+        elif self.perspective_type == "Topocentric":
+            self._iflag += swe.FLG_TOPOCTR
+            # geopos_is_set, for topocentric
+            if (self.online) and (not self.tz_str) and (not self.lat) and (not self.lng):
+                self._fetch_and_set_tz_and_coordinates_from_geonames()
+            swe.set_topo(self.lng, self.lat, 0)
+        # <--- Chart Perspective check and setup
+
+        # House System check and setup --->
+        if self.houses_system_identifier not in get_args(HousesSystemIdentifier):
+            raise KerykeionException(f"\n* ERROR: '{self.houses_system_identifier}' is NOT a valid house system! Available systems are: *" + "\n" + str(get_args(HousesSystemIdentifier)))
+
+        self.houses_system_name = swe.house_name(self.houses_system_identifier.encode('ascii'))
+        # <--- House System check and setup
+
+        # Zodiac Type and Sidereal mode checks and setup --->
+        if zodiac_type and not zodiac_type in get_args(ZodiacType):
+            raise KerykeionException(f"\n* ERROR: '{zodiac_type}' is NOT a valid zodiac type! Available types are: *" + "\n" + str(get_args(ZodiacType)))
+
+        if self.sidereal_mode and self.zodiac_type == "Tropic":
+            raise KerykeionException("You can't set a sidereal mode with a Tropic zodiac type!")
+        
+        if self.zodiac_type == "Sidereal" and not self.sidereal_mode:
+            self.sidereal_mode = DEFAULT_SIDEREAL_MODE
+            logging.info("No sidereal mode set, using default FAGAN_BRADLEY")
+
+        if self.zodiac_type == "Sidereal":
+            # Check if the sidereal mode is valid
+            if not self.sidereal_mode in get_args(SiderealMode):
+                raise KerykeionException(f"\n* ERROR: '{self.sidereal_mode}' is NOT a valid sidereal mode! Available modes are: *" + "\n" + str(get_args(SiderealMode)))
+
+            self._iflag += swe.FLG_SIDEREAL
+            mode = "SIDM_" + self.sidereal_mode
+            swe.set_sid_mode(getattr(swe, mode))
+            logging.debug(f"Using sidereal mode: {mode}")
+        # <--- Zodiac Type and Sidereal mode checks and setup
+
+        #------------------------#
+        # Start the calculations #
+        #------------------------#
+
+        # UTC, julian day and local time setup --->
+        if (self.online) and (not self.tz_str) and (not self.lat) and (not self.lng):
+            self._fetch_and_set_tz_and_coordinates_from_geonames()
+        
+        self.lat = check_and_adjust_polar_latitude(self.lat)
+
+        # Local time to UTC
+        local_time = pytz.timezone(self.tz_str)
+        naive_datetime = datetime(self.year, self.month, self.day, self.hour, self.minute, 0)
+
+        try:
+            local_datetime = local_time.localize(naive_datetime, is_dst=self.is_dst)
+        except pytz.exceptions.AmbiguousTimeError:
+            raise KerykeionException("Ambiguous time! Please specify if the time is in DST or not with the is_dst argument.")
+
+        utc_object = local_datetime.astimezone(pytz.utc)
+        self.iso_formatted_utc_datetime = utc_object.isoformat()
+
+        # ISO formatted local datetime
+        self.iso_formatted_local_datetime = local_datetime.isoformat()
+
+        # Julian day calculation
+        utc_float_hour_with_minutes = utc_object.hour + (utc_object.minute / 60)
+        self.julian_day = float(swe.julday(utc_object.year, utc_object.month, utc_object.day, utc_float_hour_with_minutes))
+        # <--- UTC, julian day and local time setup
 
-        # Initialize everything
-        self._get_utc()
-        self._get_jd()
         self._planets_degrees_lister()
         self._planets()
         self._houses()
-
         self._planets_in_houses()
         self._lunar_phase_calc()
 
+        # Deprecated properties
+        self.utc_time
+        self.local_time
+
     def __str__(self) -> str:
-        return f"Astrological data for: {self.name}, {self.utc} UTC\nBirth location: {self.city}, Lat {self.lat}, Lon {self.lng}"
+        return f"Astrological data for: {self.name}, {self.iso_formatted_utc_datetime} UTC\nBirth location: {self.city}, Lat {self.lat}, Lon {self.lng}"
 
     def __repr__(self) -> str:
-        return f"Astrological data for: {self.name}, {self.utc} UTC\nBirth location: {self.city}, Lat {self.lat}, Lon {self.lng}"
+        return f"Astrological data for: {self.name}, {self.iso_formatted_utc_datetime} UTC\nBirth location: {self.city}, Lat {self.lat}, Lon {self.lng}"
 
     def __getitem__(self, item):
         return getattr(self, item)
@@ -234,7 +359,7 @@ class AstrologicalSubject:
     def get(self, item, default=None):
         return getattr(self, item, default)
 
-    def _fetch_tz_from_geonames(self) -> None:
+    def _fetch_and_set_tz_and_coordinates_from_geonames(self) -> None:
         """Gets the nearest time zone for the calculation"""
         logging.info("Fetching timezone/coordinates from geonames")
 
@@ -258,33 +383,6 @@ class AstrologicalSubject:
         self.lat = float(self.city_data["lat"])
         self.tz_str = self.city_data["timezonestr"]
 
-        self._check_if_poles()
-
-    def _get_utc(self) -> None:
-        """Converts local time to utc time."""
-
-        # If the coordinates are not set, get them from geonames.
-        if (self.online) and (not self.tz_str):
-            self._fetch_tz_from_geonames()
-
-        # If UTC datetime is provided, then use it directly
-        if (self.utc_datetime):
-            self.utc = self.utc_datetime
-            return
-
-        local_time = pytz.timezone(self.tz_str)
-
-        naive_datetime = datetime(self.year, self.month, self.day, self.hour, self.minute, 0)
-
-        local_datetime = local_time.localize(naive_datetime, is_dst=None)
-        self.utc = local_datetime.astimezone(pytz.utc)
-
-    def _get_jd(self) -> None:
-        """Calculates julian day from the utc time."""
-        self.utc_time = self.utc.hour + self.utc.minute / 60
-        self.local_time = self.hour + self.minute / 60
-        self.julian_day = float(swe.julday(self.utc.year, self.utc.month, self.utc.day, self.utc_time))
-
     def _houses(self) -> None:
         """
         Calculate positions and store them in dictionaries
@@ -321,18 +419,21 @@ class AstrologicalSubject:
 
         if self.zodiac_type == "Sidereal":
             self.houses_degree_ut = swe.houses_ex(
-                tjdut=self.julian_day, lat=self.lat, lon=self.lng, hsys=str.encode('P'), flags=swe.FLG_SIDEREAL
+                tjdut=self.julian_day,
+                lat=self.lat, lon=self.lng,
+                hsys=str.encode(self.houses_system_identifier),
+                flags=swe.FLG_SIDEREAL
             )[0]
+
         elif self.zodiac_type == "Tropic":
             self.houses_degree_ut = swe.houses(
-                tjdut=self.julian_day, lat=self.lat, lon=self.lng, hsys=str.encode('P')
+                tjdut=self.julian_day, lat=self.lat,
+                lon=self.lng,
+                hsys=str.encode(self.houses_system_identifier)
             )[0]
-        else:
-            raise KerykeionException("Zodiac type not recognized! Please use 'Tropic' or 'Sidereal'")
 
-        point_type: Literal["Planet", "House"] = "House"
-        # creates the list of the house in 360°
-        self.houses_degree_ut = swe.houses(self.julian_day, self.lat, self.lng)[0]
+        point_type: PointType = "House"
+
         # stores the house in singular dictionaries.
         self.first_house = calculate_position(self.houses_degree_ut[0], "First_House", point_type=point_type)
         self.second_house = calculate_position(self.houses_degree_ut[1], "Second_House", point_type=point_type)
@@ -364,12 +465,6 @@ class AstrologicalSubject:
 
     def _planets_degrees_lister(self):
         """Sidereal or tropic mode."""
-        self._iflag = swe.FLG_SWIEPH + swe.FLG_SPEED
-
-        if self.zodiac_type == "Sidereal":
-            self._iflag += swe.FLG_SIDEREAL
-            mode = "SIDM_FAGAN_BRADLEY"
-            swe.set_sid_mode(getattr(swe, mode))
 
         # Calculates the position of the planets and stores it in a list.
         sun_deg = swe.calc(self.julian_day, 0, self._iflag)[0][0]
@@ -384,11 +479,6 @@ class AstrologicalSubject:
         pluto_deg = swe.calc(self.julian_day, 9, self._iflag)[0][0]
         mean_node_deg = swe.calc(self.julian_day, 10, self._iflag)[0][0]
         true_node_deg = swe.calc(self.julian_day, 11, self._iflag)[0][0]
-        
-        if not self.disable_chiron:
-            chiron_deg = swe.calc(self.julian_day, 15, self._iflag)[0][0]
-        else:
-            chiron_deg = 0
 
         self.planets_degrees_ut = [
             sun_deg,
@@ -405,14 +495,23 @@ class AstrologicalSubject:
             true_node_deg,
         ]
         
-        if not self.disable_chiron:
+        if not self.disable_chiron_and_lilith:
+            chiron_deg = swe.calc(self.julian_day, 15, self._iflag)[0][0]
             self.planets_degrees_ut.append(chiron_deg)
 
+            mean_lilith_deg = swe.calc(self.julian_day, 12, self._iflag)[0][0]
+            self.planets_degrees_ut.append(mean_lilith_deg)
+
+        else:
+            self.chiron = None
+            self.mean_lilith = None
+
+
     def _planets(self) -> None:
         """Defines body positon in signs and information and
         stores them in dictionaries"""
 
-        point_type: Literal["Planet", "House"] = "Planet"
+        point_type: PointType = "Planet"
         # stores the planets in singular dictionaries.
         self.sun = calculate_position(self.planets_degrees_ut[0], "Sun", point_type=point_type)
         self.moon = calculate_position(self.planets_degrees_ut[1], "Moon", point_type=point_type)
@@ -427,10 +526,14 @@ class AstrologicalSubject:
         self.mean_node = calculate_position(self.planets_degrees_ut[10], "Mean_Node", point_type=point_type)
         self.true_node = calculate_position(self.planets_degrees_ut[11], "True_Node", point_type=point_type)
         
-        if not self.disable_chiron:
+        if not self.disable_chiron_and_lilith:
             self.chiron = calculate_position(self.planets_degrees_ut[12], "Chiron", point_type=point_type)
+            self.mean_lilith = calculate_position(self.planets_degrees_ut[13], "Mean_Lilith", point_type=point_type)
+
         else:
             self.chiron = None
+            self.mean_lilith = None
+
 
     def _planets_in_houses(self) -> None:
         """Calculates the house of the planet and updates
@@ -449,11 +552,6 @@ class AstrologicalSubject:
         self.mean_node.house = get_planet_house(self.planets_degrees_ut[10], self.houses_degree_ut)
         self.true_node.house = get_planet_house(self.planets_degrees_ut[11], self.houses_degree_ut)
 
-        if not self.disable_chiron:
-            self.chiron.house = get_planet_house(self.planets_degrees_ut[12], self.houses_degree_ut)
-        else:
-            self.chiron = None
-
         self.planets_list = [
             self.sun,
             self.moon,
@@ -469,18 +567,26 @@ class AstrologicalSubject:
             self.true_node,
         ]
         
-        if not self.disable_chiron:
+        if not self.disable_chiron_and_lilith:
+            self.chiron.house = get_planet_house(self.planets_degrees_ut[12], self.houses_degree_ut)
             self.planets_list.append(self.chiron)
 
+            self.mean_lilith.house = get_planet_house(self.planets_degrees_ut[13], self.houses_degree_ut)
+            self.planets_list.append(self.mean_lilith)
+
+        else:
+            self.chiron = None
+            self.mean_lilith = None
+
         # Check in retrograde or not:
         planets_ret = []
-        for p in self.planets_list:
-            planet_number = get_number_from_name(p["name"])
+        for planet in self.planets_list:
+            planet_number = get_number_from_name(planet["name"])
             if swe.calc(self.julian_day, planet_number, self._iflag)[0][3] < 0:
-                p["retrograde"] = True
+                planet["retrograde"] = True
             else:
-                p["retrograde"] = False
-            planets_ret.append(p)
+                planet["retrograde"] = False
+            planets_ret.append(planet)
 
     def _lunar_phase_calc(self) -> None:
         """Function to calculate the lunar phase"""
@@ -555,20 +661,7 @@ class AstrologicalSubject:
 
         self.lunar_phase = LunarPhaseModel(**lunar_phase_dictionary)
 
-    def _check_if_poles(self):
-        """
-            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 self.lat > 66.0:
-            self.lat = 66.0
-            logging.info("Polar circle override for houses, using 66 degrees")
-
-        elif self.lat < -66.0:
-            self.lat = -66.0
-            logging.info("Polar circle override for houses, using -66 degrees")
-
-    def json(self, dump=False, destination_folder: Union[str, None] = None) -> str:
+    def json(self, dump=False, destination_folder: Union[str, None] = None, indent: Union[int, None] = None) -> str:
         """
         Dumps the Kerykeion object to a json string foramt,
         if dump=True also dumps to file located in destination
@@ -576,8 +669,7 @@ class AstrologicalSubject:
         """
 
         KrData = AstrologicalSubjectModel(**self.__dict__)
-        json_string = KrData.model_dump_json(exclude_none=True)
-        print(json_string)
+        json_string = KrData.model_dump_json(exclude_none=True, indent=indent)
 
         if dump:
             if destination_folder:
@@ -600,6 +692,131 @@ class AstrologicalSubject:
 
         return AstrologicalSubjectModel(**self.__dict__)
 
+    @cached_property
+    def utc_time(self) -> float:
+        """
+        Deprecated property, use iso_formatted_utc_datetime instead, will be removed in the future.
+        Returns the UTC time as a float.
+        """
+        dt = datetime.fromisoformat(self.iso_formatted_utc_datetime)
+        
+        # Extract the hours, minutes, and seconds
+        hours = dt.hour
+        minutes = dt.minute
+        seconds = dt.second + dt.microsecond / 1_000_000
+
+        # Convert time to float hours
+        float_time = hours + minutes / 60 + seconds / 3600
+
+        return float_time
+
+    @cached_property
+    def local_time(self) -> float:
+        """
+        Deprecated property, use iso_formatted_local_datetime instead, will be removed in the future.
+        Returns the local time as a float.
+        """
+        dt = datetime.fromisoformat(self.iso_formatted_local_datetime)
+        
+        # Extract the hours, minutes, and seconds
+        hours = dt.hour
+        minutes = dt.minute
+        seconds = dt.second + dt.microsecond / 1_000_000
+
+        # Convert time to float hours
+        float_time = hours + minutes / 60 + seconds / 3600
+
+        return float_time
+
+
+    @staticmethod
+    def get_from_iso_utc_time(
+        name: str,
+        iso_utc_time: str, 
+        city: str = "Greenwich", 
+        nation: str = "GB",
+        tz_str: str = "Etc/GMT",
+        online: bool = False,
+        lng: Union[int, float] = 0,
+        lat: Union[int, float] = 51.5074,
+        geonames_username: str = DEFAULT_GEONAMES_USERNAME,
+        zodiac_type: ZodiacType = DEFAULT_ZODIAC_TYPE,
+        disable_chiron_and_lilith: bool = False,
+        sidereal_mode: Union[SiderealMode, None] = None,
+        houses_system_identifier: HousesSystemIdentifier = DEFAULT_HOUSES_SYSTEM_IDENTIFIER,
+        perspective_type: PerspectiveType = DEFAULT_PERSPECTIVE_TYPE
+        
+    ) -> "AstrologicalSubject":
+        """
+        Creates an AstrologicalSubject object from an iso formatted UTC time.
+        This method is offline by default, set online=True to fetch the timezone and coordinates from geonames.
+
+        Args:
+        - name (str): The name of the subject.
+        - iso_utc_time (str): The iso formatted UTC time.
+        - city (str, optional): City or location of birth. Defaults to "Greenwich".
+        - nation (str, optional): Nation of birth. Defaults to "GB".
+        - tz_str (str, optional): Timezone of the birth location. Defaults to "Etc/GMT".
+        - online (bool, optional): Sets if you want to use the online mode, which fetches the timezone and coordinates from geonames.
+            If you already have the coordinates and timezone, set this to False. Defaults to False.
+        - lng (Union[int, float], optional): Longitude of the birth location. Defaults to 0 (Greenwich, London).
+        - lat (Union[int, float], optional): Latitude of the birth location. Defaults to 51.5074 (Greenwich, London).
+        - geonames_username (str, optional): The username for the geonames API. Note: Change this to your own username to avoid rate limits!
+            You can get one for free here: https://www.geonames.org/login
+        - zodiac_type (ZodiacType, optional): The zodiac type to use. Defaults to "Tropic".
+        - disable_chiron_and_lilith: boolean representing if Chiron and Lilith should be disabled. Default is False.
+            Chiron calculation can create some issues with the Swiss Ephemeris when the date is too far in the past.
+        - sidereal_mode (SiderealMode, optional): Also known as Ayanamsa.
+            The mode to use for the sidereal zodiac, according to the Swiss Ephemeris.
+            Defaults to None.
+            Available modes are visible in the SiderealMode Literal.
+        - houses_system_identifier (HousesSystemIdentifier, optional): The system to use for the calculation of the houses.
+            Defaults to "P" (Placidus).
+            Available systems are visible in the HousesSystemIdentifier Literal.
+        - perspective_type (PerspectiveType, optional): The perspective to use for the calculation of the chart.
+            Defaults to "Apparent Geocentric".
+
+        Returns:
+        - AstrologicalSubject: The AstrologicalSubject object.
+        """
+        dt = datetime.fromisoformat(iso_utc_time)
+
+        if online == True:
+            if geonames_username == DEFAULT_GEONAMES_USERNAME:
+                logging.warning(GEONAMES_DEFAULT_USERNAME_WARNING)
+
+            geonames = FetchGeonames(
+                city,
+                nation,
+                username=geonames_username,
+            )
+
+            city_data: dict[str, str] = geonames.get_serialized_data()
+            lng = float(city_data["lng"])
+            lat = float(city_data["lat"])
+
+        subject = AstrologicalSubject(
+            name=name,
+            year=dt.year,
+            month=dt.month,
+            day=dt.day,
+            hour=dt.hour,
+            minute=dt.minute,
+            city=city,
+            nation=city,
+            lng=lng,
+            lat=lat,
+            tz_str=tz_str,
+            online=False,
+            geonames_username=geonames_username,
+            zodiac_type=zodiac_type,
+            sidereal_mode=sidereal_mode,
+            houses_system_identifier=houses_system_identifier,
+            perspective_type=perspective_type,
+            disable_chiron_and_lilith=disable_chiron_and_lilith
+        )
+
+        return subject
 
 if __name__ == "__main__":
     import json
@@ -620,3 +837,26 @@ if __name__ == "__main__":
 
     print('\n')
     print(johnny.chiron)
+
+    # With Sidereal Zodiac
+    johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", zodiac_type="Sidereal", sidereal_mode="LAHIRI")
+    print(johnny.json(dump=True, indent=2))
+
+    # With Morinus Houses
+    johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", houses_system_identifier="M")
+    print(johnny.json(dump=True, indent=2))
+
+    # With True Geocentric Perspective
+    johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", perspective_type="True Geocentric")
+    print(johnny.json(dump=True, indent=2))
+
+    # With Heliocentric Perspective
+    johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", perspective_type="Heliocentric")
+    print(johnny.json(dump=True, indent=2))
+
+    # With Topocentric Perspective
+    johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", perspective_type="Topocentric")
+
+    # Test Mean Lilith
+    johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", disable_chiron_and_lilith=True)
+    print(johnny.mean_lilith)