kerykeion 4.11.1__tar.gz → 4.12.1__tar.gz

{kerykeion-4.11.1 → kerykeion-4.12.1}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.1
 Name: kerykeion
-Version: 4.11.1
+Version: 4.12.1
 Summary: A python library for astrology.
-Home-page: https://github.com/g-battaglia/kerykeion
+Home-page: https://www.kerykeion.net/
 License: AGPL-3.0
 Keywords: astrology,ephemeris,astrology library,birtchart,svg,zodiac,zodiac-sing,astronomical-algorithms,synastry,astrology-calculator
 Author: Giacomo Battaglia
@@ -142,7 +142,7 @@ If you omit the nation, it will be set to "GB" by default, but the value is not
 ```python
 from kerykeion import AstrologicalSubject, KerykeionChartSVG
 
-first = AstrologicalSubject("John Lennon", 1940, 10, 9, 10, 30, "Liverpool", "GB")
+first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
 
 # Set the type, it can be Natal, Synastry or Transit
@@ -153,13 +153,12 @@ synastry_chart.makeSVG()
 
 ![John Lennon and Paul McCartney Synastry](https://www.kerykeion.net/assets/img/examples/synastry-chart.svg)
 
-
 Note: By default, the generated SVG file will be in the home directory! To change the destination directory:
 
 ```python
 from kerykeion import AstrologicalSubject, KerykeionChartSVG
 
-first = AstrologicalSubject("John Lennon", 1940, 10, 9, 10, 30, "Liverpool", "GB")
+first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
 
 # Synastry Chart
@@ -167,6 +166,12 @@ synastry_chart = KerykeionChartSVG(first, "Synastry", second, new_output_directo
 synastry_chart.makeSVG()
 ```
 
+### Change Language
+
+To change the language of the chart you should create a new kr.config.js file and pass it to the BirthChartSVG class. So far the available languages are English, Portuguese, Italian, Spanish, French and Chinese.
+
+Some examples [here](https://www.kerykeion.net/docs/examples/change-language).
+
 ## Report
 
 To print a report of all the data:
@@ -276,6 +281,19 @@ Full list of supported house systems [here](https://www.kerykeion.net/pydocs/ker
 
 So far all the available houses system in the Swiss Ephemeris are supported but the Gauquelin Sectors.
 
+## Perspective Type
+
+The perspective indicates the point of view from which the chart is calculated (Es. Apparent Geocentric, Heliocentric, etc.).
+You can set the perspective type in the AstrologicalSubject class:
+
+```python
+johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", perspective_type="Heliocentric")
+```
+
+More examples [here](https://www.kerykeion.net/docs/examples/perspective-type/).
+
+Full list of supported perspective types [here](https://www.kerykeion.net/pydocs/kerykeion/kr_types/kr_literals.html#PerspectiveType).
+
 ## Documentation
 
 Most of the functions and the classes are self documented by the types and have docstrings.

{kerykeion-4.11.1 → kerykeion-4.12.1}/README.md

@@ -105,7 +105,7 @@ If you omit the nation, it will be set to "GB" by default, but the value is not
 ```python
 from kerykeion import AstrologicalSubject, KerykeionChartSVG
 
-first = AstrologicalSubject("John Lennon", 1940, 10, 9, 10, 30, "Liverpool", "GB")
+first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
 
 # Set the type, it can be Natal, Synastry or Transit
@@ -116,13 +116,12 @@ synastry_chart.makeSVG()
 
 ![John Lennon and Paul McCartney Synastry](https://www.kerykeion.net/assets/img/examples/synastry-chart.svg)
 
-
 Note: By default, the generated SVG file will be in the home directory! To change the destination directory:
 
 ```python
 from kerykeion import AstrologicalSubject, KerykeionChartSVG
 
-first = AstrologicalSubject("John Lennon", 1940, 10, 9, 10, 30, "Liverpool", "GB")
+first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
 
 # Synastry Chart
@@ -130,6 +129,12 @@ synastry_chart = KerykeionChartSVG(first, "Synastry", second, new_output_directo
 synastry_chart.makeSVG()
 ```
 
+### Change Language
+
+To change the language of the chart you should create a new kr.config.js file and pass it to the BirthChartSVG class. So far the available languages are English, Portuguese, Italian, Spanish, French and Chinese.
+
+Some examples [here](https://www.kerykeion.net/docs/examples/change-language).
+
 ## Report
 
 To print a report of all the data:
@@ -239,6 +244,19 @@ Full list of supported house systems [here](https://www.kerykeion.net/pydocs/ker
 
 So far all the available houses system in the Swiss Ephemeris are supported but the Gauquelin Sectors.
 
+## Perspective Type
+
+The perspective indicates the point of view from which the chart is calculated (Es. Apparent Geocentric, Heliocentric, etc.).
+You can set the perspective type in the AstrologicalSubject class:
+
+```python
+johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", perspective_type="Heliocentric")
+```
+
+More examples [here](https://www.kerykeion.net/docs/examples/perspective-type/).
+
+Full list of supported perspective types [here](https://www.kerykeion.net/pydocs/kerykeion/kr_types/kr_literals.html#PerspectiveType).
+
 ## Documentation
 
 Most of the functions and the classes are self documented by the types and have docstrings.

{kerykeion-4.11.1 → kerykeion-4.12.1}/kerykeion/aspects/synastry_aspects.py

@@ -95,8 +95,8 @@ if __name__ == "__main__":
     from kerykeion.utilities import setup_logging
     setup_logging(level="debug")
 
-    john = AstrologicalSubject("John", 1940, 10, 9, 10, 30, "Liverpool")
-    yoko = AstrologicalSubject("Yoko", 1933, 2, 18, 10, 30, "Tokyo")
+    john = AstrologicalSubject("John", 1940, 10, 9, 18, 30, "Liverpool")
+    yoko = AstrologicalSubject("Yoko", 1933, 2, 18, 18, 30, "Tokyo")
 
     synastry_aspects = SynastryAspects(john, yoko)
 

{kerykeion-4.11.1 → kerykeion-4.12.1}/kerykeion/astrological_subject.py

@@ -8,6 +8,7 @@ import swisseph as swe
 import logging
 
 from datetime import datetime
+from functools import cached_property
 from kerykeion.fetch_geonames import FetchGeonames
 from kerykeion.kr_types import (
     KerykeionException,
@@ -17,7 +18,8 @@ from kerykeion.kr_types import (
     KerykeionPointModel,
     PointType,
     SiderealMode,
-    HousesSystemIdentifier
+    HousesSystemIdentifier,
+    PerspectiveType
 )
 from kerykeion.utilities import (
     get_number_from_name, 
@@ -25,6 +27,7 @@ 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, get_args
@@ -32,6 +35,8 @@ from typing import Union, get_args
 DEFAULT_GEONAMES_USERNAME = "century.boy"
 DEFAULT_SIDEREAL_MODE = "FAGAN_BRADLEY"
 DEFAULT_HOUSES_SYSTEM = "P"
+PERSPECTIVE_TYPE = "Apparent Geocentric"
+NOW = datetime.now()
 
 
 class AstrologicalSubject:
@@ -40,27 +45,25 @@ 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.
+    - 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 (bool, optional): Disables the calculation of Chiron. Defaults to 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. 
@@ -68,11 +71,15 @@ class AstrologicalSubject:
         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.
     """
 
     # Defined by the user
     name: str
-    utc_datetime: Union[datetime, None]
     year: int
     month: int
     day: int
@@ -89,14 +96,14 @@ class AstrologicalSubject:
     sidereal_mode: SiderealMode
     houses_system_identifier: HousesSystemIdentifier
     houses_system_name: str
+    perspective_type: PerspectiveType
 
     # 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
@@ -133,16 +140,14 @@ class AstrologicalSubject:
     planets_degrees_ut: list[float]
     houses_degree_ut: list[float]
 
-    now = datetime.now()
-
     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,
@@ -151,19 +156,13 @@ class AstrologicalSubject:
         geonames_username: Union[str, None] = None,
         zodiac_type: ZodiacType = "Tropic",
         online: bool = True,
-        utc_datetime: Union[datetime, None] = None,
         disable_chiron: bool = False,
         sidereal_mode: Union[SiderealMode, None] = None,
-        houses_system_identifier: HousesSystemIdentifier = DEFAULT_HOUSES_SYSTEM
+        houses_system_identifier: HousesSystemIdentifier = DEFAULT_HOUSES_SYSTEM,
+        perspective_type: PerspectiveType = PERSPECTIVE_TYPE
     ) -> None:
         logging.debug("Starting Kerykeion")
 
-        # We set the swisseph path to the current directory
-        swe.set_ephe_path(str(Path(__file__).parent.absolute() / "sweph"))
-        
-        # Flags for the Swiss Ephemeris
-        self._iflag = swe.FLG_SWIEPH + swe.FLG_SPEED
-
         self.name = name
         self.year = year
         self.month = month
@@ -179,39 +178,14 @@ 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
 
-        # 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
+        #---------------#
+        # General setup #
+        #---------------#
 
         # This message is set to encourage the user to set a custom geonames username
         if geonames_username is None and online:
@@ -253,23 +227,99 @@ class AstrologicalSubject:
         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!")
 
-        self._check_if_poles()
+        #-----------------------#
+        # Swiss Ephemeris setup #
+        #-----------------------#
+
+        # We set the swisseph path to the current directory
+        swe.set_ephe_path(str(Path(__file__).parent.absolute() / "sweph"))
+
+        # 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
+            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 #
+        #------------------------#
+        
+        check_and_adjust_polar_latitude(self.lat, self.lng)
+
+        # UTC, julian day and local time setup --->
+        if (self.online) and (not self.tz_str):
+            self._fetch_tz_from_geonames()
+
+        # 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)
+        local_datetime = local_time.localize(naive_datetime, is_dst=None)
+        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)
@@ -301,32 +351,7 @@ 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))
+        check_and_adjust_polar_latitude(self.lat, self.lng)
 
     def _houses(self) -> None:
         """
@@ -595,19 +620,6 @@ 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, indent: Union[int, None] = None) -> str:
         """
         Dumps the Kerykeion object to a json string foramt,
@@ -639,6 +651,41 @@ 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
 
 if __name__ == "__main__":
     import json
@@ -666,4 +713,19 @@ if __name__ == "__main__":
 
     # 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))
+    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")
+
+    # Print the utc time
+    print(johnny.utc_time)
+    print(johnny.local_time)

{kerykeion-4.11.1 → kerykeion-4.12.1}/kerykeion/charts/kerykeion_chart_svg.py

@@ -33,6 +33,7 @@ from pathlib import Path
 from scour.scour import scourString
 from string import Template
 from typing import Union, List
+from datetime import datetime
 
 
 
@@ -1017,7 +1018,7 @@ class KerykeionChartSVG:
         li = 10
         offset = 0
 
-        out = '<g transform="translate(500,-20)">'
+        out = '<g transform="translate(510,-20)">'
         out += '<g transform="translate(140, -15)">'
         out += f'<text text-anchor="end" style="fill:{self.chart_colors_settings["paper_0"]}; font-size: 14px;">{self.language_settings["planets_and_house"]} {self.user.name}:</text>'
         out += "</g>"
@@ -1108,7 +1109,7 @@ class KerykeionChartSVG:
         Returns:
             str: The SVG code for the grid of houses.
         """
-        out = '<g transform="translate(600,-20)">'
+        out = '<g transform="translate(610,-20)">'
 
         li = 10
         for i in range(12):
@@ -1126,8 +1127,10 @@ class KerykeionChartSVG:
         out += "</g>"
 
         if self.chart_type == "Synastry":
-            out += '<g transform="translate(840, -20)">'
+            out += '<!-- Synastry Houses -->'
+            out += '<g transform="translate(850, -20)">'
             li = 10
+
             for i in range(12):
                 if i < 9:
                     cusp = "&#160;&#160;" + str(i + 1)
@@ -1236,16 +1239,16 @@ class KerykeionChartSVG:
         if self.chart_type == "Natal" or self.chart_type == "ExternalNatal" or self.chart_type == "Synastry":
             td["bottomLeft0"] = f"{self.user.zodiac_type if self.user.zodiac_type == 'Tropic' else self.user.zodiac_type + ' ' + self.user.sidereal_mode}"
             td["bottomLeft1"] = f"{self.user.houses_system_name}"
-            td["bottomLeft2"] = f'{self.language_settings.get("lunar_phase", "Lunar Phase")}: {self.user.lunar_phase.moon_phase_name}'
-            td["bottomLeft3"] = f'{self.language_settings.get("lunar_phase", "Lunar Phase")}: {self.language_settings.get("day", "Day")} {self.user.lunar_phase.get("moon_phase", "")}'
-            td["bottomLeft4"] = ""
+            td["bottomLeft2"] = f'{self.language_settings.get("lunar_phase", "Lunar Phase")}: {self.language_settings.get("day", "Day")} {self.user.lunar_phase.get("moon_phase", "")}'
+            td["bottomLeft3"] = f'{self.language_settings.get("lunar_phase", "Lunar Phase")}: {self.user.lunar_phase.moon_phase_name}'
+            td["bottomLeft4"] = f'{self.user.perspective_type}'
 
         else:
             td["bottomLeft0"] = f"{self.user.zodiac_type if self.user.zodiac_type == 'Tropic' else self.user.zodiac_type + ' ' + self.user.sidereal_mode}"
             td["bottomLeft1"] = f"{self.user.houses_system_name}"
-            td["bottomLeft2"] = f'{self.language_settings.get("lunar_phase", "Lunar Phase")}: {self.t_user.lunar_phase.moon_phase_name}'
-            td["bottomLeft3"] = f'{self.language_settings.get("lunar_phase", "Lunar Phase")}: {self.language_settings.get("day", "Day")} {self.t_user.lunar_phase.get("moon_phase", "")}'
-            td["bottomLeft4"] = ""
+            td["bottomLeft2"] = f'{self.language_settings.get("lunar_phase", "Lunar Phase")}: {self.language_settings.get("day", "Day")} {self.t_user.lunar_phase.get("moon_phase", "")}'
+            td["bottomLeft3"] = f'{self.language_settings.get("lunar_phase", "Lunar Phase")}: {self.t_user.lunar_phase.moon_phase_name}'
+            td["bottomLeft4"] = f'{self.t_user.perspective_type}'
 
         # lunar phase
         deg = self.user.lunar_phase["degrees_between_s_m"]
@@ -1313,8 +1316,6 @@ class KerykeionChartSVG:
         else:
             td["stringLocation"] = self.location
 
-        td["stringDateTime"] = f"{self.user.year}-{self.user.month}-{self.user.day} {self.user.hour:02d}:{self.user.minute:02d}"
-
         if self.chart_type == "Synastry":
             td["stringLat"] = f"{self.t_user.name}: "
             td["stringLon"] = self.t_user.city
@@ -1378,6 +1379,12 @@ class KerykeionChartSVG:
         )
         td["makePlanetGrid"] = self._makePlanetGrid()
 
+        # Date time String
+        dt = datetime.fromisoformat(self.user.iso_formatted_local_datetime)
+        custom_format = dt.strftime('%Y-%-m-%-d %H:%M [%z]')  # Note the use of '-' to remove leading zeros
+        custom_format = custom_format[:-3] + ':' + custom_format[-3:]
+        td["stringDateTime"] = f"{custom_format}"
+
         return td
 
     def makeTemplate(self, minify: bool = False) -> str:
@@ -1420,7 +1427,7 @@ if __name__ == "__main__":
     from kerykeion.utilities import setup_logging
     setup_logging(level="debug")
 
-    first = AstrologicalSubject("John Lennon", 1940, 10, 9, 10, 30, "Liverpool", "GB")
+    first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
     second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
 
     # Internal Natal Chart
@@ -1440,27 +1447,27 @@ if __name__ == "__main__":
     transits_chart.makeSVG()
     
     # Sidereal Birth Chart (Lahiri)
-    sidereal_subject = AstrologicalSubject("John Lennon Lahiri", 1940, 10, 9, 10, 30, "Liverpool", "GB", zodiac_type="Sidereal", sidereal_mode="LAHIRI")
+    sidereal_subject = AstrologicalSubject("John Lennon Lahiri", 1940, 10, 9, 18, 30, "Liverpool", "GB", zodiac_type="Sidereal", sidereal_mode="LAHIRI")
     sidereal_chart = KerykeionChartSVG(sidereal_subject)
     sidereal_chart.makeSVG()
 
     # Sidereal Birth Chart (Fagan-Bradley)
-    sidereal_subject = AstrologicalSubject("John Lennon Fagan-Bradley", 1940, 10, 9, 10, 30, "Liverpool", "GB", zodiac_type="Sidereal", sidereal_mode="FAGAN_BRADLEY")
+    sidereal_subject = AstrologicalSubject("John Lennon Fagan-Bradley", 1940, 10, 9, 18, 30, "Liverpool", "GB", zodiac_type="Sidereal", sidereal_mode="FAGAN_BRADLEY")
     sidereal_chart = KerykeionChartSVG(sidereal_subject)
     sidereal_chart.makeSVG()
 
     # Sidereal Birth Chart (DeLuce)
-    sidereal_subject = AstrologicalSubject("John Lennon DeLuce", 1940, 10, 9, 10, 30, "Liverpool", "GB", zodiac_type="Sidereal", sidereal_mode="DELUCE")
+    sidereal_subject = AstrologicalSubject("John Lennon DeLuce", 1940, 10, 9, 18, 30, "Liverpool", "GB", zodiac_type="Sidereal", sidereal_mode="DELUCE")
     sidereal_chart = KerykeionChartSVG(sidereal_subject)
     sidereal_chart.makeSVG()
 
     # Sidereal Birth Chart (J2000)
-    sidereal_subject = AstrologicalSubject("John Lennon J2000", 1940, 10, 9, 10, 30, "Liverpool", "GB", zodiac_type="Sidereal", sidereal_mode="J2000")
+    sidereal_subject = AstrologicalSubject("John Lennon J2000", 1940, 10, 9, 18, 30, "Liverpool", "GB", zodiac_type="Sidereal", sidereal_mode="J2000")
     sidereal_chart = KerykeionChartSVG(sidereal_subject)
     sidereal_chart.makeSVG()
 
     # House System Morinus
-    morinus_house_subject = AstrologicalSubject("John Lennon - House System Morinus", 1940, 10, 9, 10, 30, "Liverpool", "GB", houses_system_identifier="M")
+    morinus_house_subject = AstrologicalSubject("John Lennon - House System Morinus", 1940, 10, 9, 18, 30, "Liverpool", "GB", houses_system_identifier="M")
     morinus_house_chart = KerykeionChartSVG(morinus_house_subject)
     morinus_house_chart.makeSVG()
 
@@ -1468,6 +1475,21 @@ if __name__ == "__main__":
     # from kerykeion.kr_types import HousesSystemIdentifier
     # from typing import get_args
     # for i in get_args(HousesSystemIdentifier):
-    #     alternatives_house_subject = AstrologicalSubject(f"John Lennon - House System {i}", 1940, 10, 9, 10, 30, "Liverpool", "GB", houses_system=i)
+    #     alternatives_house_subject = AstrologicalSubject(f"John Lennon - House System {i}", 1940, 10, 9, 18, 30, "Liverpool", "GB", houses_system=i)
     #     alternatives_house_chart = KerykeionChartSVG(alternatives_house_subject)
     #     alternatives_house_chart.makeSVG()
+
+    # With True Geocentric Perspective
+    true_geocentric_subject = AstrologicalSubject("John Lennon - True Geocentric", 1940, 10, 9, 18, 30, "Liverpool", "GB", perspective_type="True Geocentric")
+    true_geocentric_chart = KerykeionChartSVG(true_geocentric_subject)
+    true_geocentric_chart.makeSVG()
+
+    # With Heliocentric Perspective
+    heliocentric_subject = AstrologicalSubject("John Lennon - Heliocentric", 1940, 10, 9, 18, 30, "Liverpool", "GB", perspective_type="Heliocentric")
+    heliocentric_chart = KerykeionChartSVG(heliocentric_subject)
+    heliocentric_chart.makeSVG()
+
+    # With Topocentric Perspective
+    topocentric_subject = AstrologicalSubject("John Lennon - Topocentric", 1940, 10, 9, 18, 30, "Liverpool", "GB", perspective_type="Topocentric")
+    topocentric_chart = KerykeionChartSVG(topocentric_subject)
+    topocentric_chart.makeSVG()

{kerykeion-4.11.1 → kerykeion-4.12.1}/kerykeion/charts/templates/chart.xml

@@ -14,18 +14,18 @@
         <g transform="scale($cfgZoom)">
             <rect class="background-rectangle" x="0" y="0" width="$chart_width"
                 height="$chart_height" style="fill: $paper_color_1" />
-            <text x="20" y="30" style="fill: $paper_color_0; font-size: 24px">$stringTitle</text>
+            <text x="20" y="22" style="fill: $paper_color_0; font-size: 24px">$stringTitle</text>
             <text x="20" y="50" style="fill: $paper_color_0; font-size: 11px">$stringName</text>
             <text x="20" y="62" style="fill: $paper_color_0; font-size: 11px">$stringLocation</text>
             <text x="20" y="74" style="fill: $paper_color_0; font-size: 11px">$stringDateTime</text>
             <text x="20" y="86" style="fill: $paper_color_0; font-size: 11px">$stringLat</text>
             <text x="20" y="98" style="fill: $paper_color_0; font-size: 11px">$stringLon</text>
             <text x="20" y="110" style="fill: $paper_color_0; font-size: 11px">$stringPosition</text>
-            <text x="20" y="466" style="fill: $paper_color_0; font-size: 10px">$bottomLeft0</text>
-            <text x="20" y="480" style="fill: $paper_color_0; font-size: 10px">$bottomLeft1</text>
-            <text x="20" y="494" style="fill: $paper_color_0; font-size: 10px">$bottomLeft2</text>
-            <text x="20" y="508" style="fill: $paper_color_0; font-size: 10px">$bottomLeft3</text>
-            <text x="20" y="522" style="fill: $paper_color_0; font-size: 10px">$bottomLeft4</text>
+            <text x="20" y="452" style="fill: $paper_color_0; font-size: 10px">$bottomLeft0</text>
+            <text x="20" y="466" style="fill: $paper_color_0; font-size: 10px">$bottomLeft1</text>
+            <text x="20" y="480" style="fill: $paper_color_0; font-size: 10px">$bottomLeft2</text>
+            <text x="20" y="494" style="fill: $paper_color_0; font-size: 10px">$bottomLeft3</text>
+            <text x="20" y="508" style="fill: $paper_color_0; font-size: 10px">$bottomLeft4</text>
             <!-- Lunar Phase -->
             <g transform="translate(20,518)">
                 <g transform="rotate($lunar_phase_rotate 20 10)">

{kerykeion-4.11.1 → kerykeion-4.12.1}/kerykeion/kr_types/kr_literals.py

@@ -14,7 +14,7 @@ Sign = Literal["Ari", "Tau", "Gem", "Can", "Leo", "Vir", "Lib", "Sco", "Sag", "C
 
 
 SignNumbers = Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
-"""Literal type for Zodiac Sign Numbers"""
+"""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"]
@@ -22,7 +22,7 @@ Houses = Literal["First_House", "Second_House", "Third_House", "Fourth_House", "
 
 
 HouseNumbers = Literal[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
-"""Literal type for House Numbers"""
+"""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"]
@@ -87,3 +87,15 @@ 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-4.11.1 → kerykeion-4.12.1}/kerykeion/kr_types/kr_models.py

@@ -68,8 +68,9 @@ class AstrologicalSubjectModel(SubscriptableBaseModel):
     sidereal_mode: Union[SiderealMode, None]
     houses_system_identifier: HousesSystemIdentifier
     houses_system_name: str
-    local_time: float
-    utc_time: float
+    perspective_type: str
+    iso_formatted_local_datetime: str
+    iso_formatted_utc_datetime: str
     julian_day: float
 
     # Planets
@@ -108,6 +109,15 @@ class AstrologicalSubjectModel(SubscriptableBaseModel):
     # 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-4.11.1 → kerykeion-4.12.1}/kerykeion/utilities.py

@@ -354,3 +354,17 @@ def get_moon_phase_name_from_phase_int(phase: int) -> LunarPhaseName:
         raise KerykeionException(f"Error in moon name calculation! Phase: {phase}")
     
     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")

{kerykeion-4.11.1 → kerykeion-4.12.1}/pyproject.toml

@@ -1,10 +1,10 @@
 [tool.poetry]
 name = "kerykeion"
-version = "4.11.1"
+version = "4.12.1"
 authors = ["Giacomo Battaglia <battaglia.giacomo@yahoo.it>"]
 description = "A python library for astrology."
 license = "AGPL-3.0"
-homepage = "https://github.com/g-battaglia/kerykeion"
+homepage = "https://www.kerykeion.net/"
 repository = "https://github.com/g-battaglia/kerykeion"
 keywords = [
     "astrology",