kerykeion 4.12.0__tar.gz → 4.12.2__tar.gz

{kerykeion-4.12.0 → kerykeion-4.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kerykeion
-Version: 4.12.0
+Version: 4.12.2
 Summary: A python library for astrology.
 Home-page: https://www.kerykeion.net/
 License: AGPL-3.0
@@ -236,7 +236,7 @@ And if you want to export it to a file:
 python3 your_script_name.py > file.txt
 ```
 
-## Other exeples of possibles usecase
+## Other examples of possible use cases:
 
 ```python
 # Get all aspects between two persons:
@@ -257,7 +257,8 @@ print(aspect_list[0])
 
 ## Ayanamsa (Sidereal Modes)
 
-You can set the zodiac type and the sidereal mode in the AstrologicalSubject class:
+By default, the zodiac type is set to Tropic (Tropical).
+You can set the zodiac type to Sidereal and the sidereal mode in the AstrologicalSubject class:
 
 ```python
 johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", zodiac_type="Sidereal", sidereal_mode="LAHIRI")
@@ -269,6 +270,7 @@ Full list of supported sidereal modes [here](https://www.kerykeion.net/pydocs/ke
 
 ## Houses Systems
 
+By default, the houses system is set to Placidus.
 You can set the houses system in the AstrologicalSubject class:
 
 ```python
@@ -283,6 +285,7 @@ So far all the available houses system in the Swiss Ephemeris are supported but
 
 ## Perspective Type
 
+By default, the perspective type is set to Apparent Geocentric (the most common standard for astrology).
 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:
 
@@ -294,6 +297,29 @@ 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).
 
+## Alternative Initialization
+
+You can initialize the AstrologicalSubject from a **UTC** ISO 8601 string:
+
+```python
+subject = AstrologicalSubject.get_from_iso_utc_time(
+    "Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US")
+```
+
+Note : The default time zone is UTC, with Greenwich longitude and latitude.
+
+
+The default online/offline mode is set to offline, if you set it online the default latitude and longitude will be ignored and
+calculated from the city and nation. Remember to pass also the geonames_username parameter if you want to use the online mode, like this:
+
+```python
+from kerykeion.astrological_subject import AstrologicalSubject
+
+# Use the static method get_from_iso_utc_time to create an instance of AstrologicalSubject
+subject2 = AstrologicalSubject.get_from_iso_utc_time(
+    "Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US", online=True)
+```
+
 ## Documentation
 
 Most of the functions and the classes are self documented by the types and have docstrings.

{kerykeion-4.12.0 → kerykeion-4.12.2}/README.md

@@ -199,7 +199,7 @@ And if you want to export it to a file:
 python3 your_script_name.py > file.txt
 ```
 
-## Other exeples of possibles usecase
+## Other examples of possible use cases:
 
 ```python
 # Get all aspects between two persons:
@@ -220,7 +220,8 @@ print(aspect_list[0])
 
 ## Ayanamsa (Sidereal Modes)
 
-You can set the zodiac type and the sidereal mode in the AstrologicalSubject class:
+By default, the zodiac type is set to Tropic (Tropical).
+You can set the zodiac type to Sidereal and the sidereal mode in the AstrologicalSubject class:
 
 ```python
 johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", zodiac_type="Sidereal", sidereal_mode="LAHIRI")
@@ -232,6 +233,7 @@ Full list of supported sidereal modes [here](https://www.kerykeion.net/pydocs/ke
 
 ## Houses Systems
 
+By default, the houses system is set to Placidus.
 You can set the houses system in the AstrologicalSubject class:
 
 ```python
@@ -246,6 +248,7 @@ So far all the available houses system in the Swiss Ephemeris are supported but
 
 ## Perspective Type
 
+By default, the perspective type is set to Apparent Geocentric (the most common standard for astrology).
 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:
 
@@ -257,6 +260,29 @@ 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).
 
+## Alternative Initialization
+
+You can initialize the AstrologicalSubject from a **UTC** ISO 8601 string:
+
+```python
+subject = AstrologicalSubject.get_from_iso_utc_time(
+    "Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US")
+```
+
+Note : The default time zone is UTC, with Greenwich longitude and latitude.
+
+
+The default online/offline mode is set to offline, if you set it online the default latitude and longitude will be ignored and
+calculated from the city and nation. Remember to pass also the geonames_username parameter if you want to use the online mode, like this:
+
+```python
+from kerykeion.astrological_subject import AstrologicalSubject
+
+# Use the static method get_from_iso_utc_time to create an instance of AstrologicalSubject
+subject2 = AstrologicalSubject.get_from_iso_utc_time(
+    "Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US", online=True)
+```
+
 ## Documentation
 
 Most of the functions and the classes are self documented by the types and have docstrings.

{kerykeion-4.12.0 → kerykeion-4.12.2}/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,
@@ -35,6 +36,16 @@ DEFAULT_GEONAMES_USERNAME = "century.boy"
 DEFAULT_SIDEREAL_MODE = "FAGAN_BRADLEY"
 DEFAULT_HOUSES_SYSTEM = "P"
 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()
 
 
@@ -189,20 +200,7 @@ class AstrologicalSubject:
         # 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" +
-                "********"
+
             )
 
             self.geonames_username = DEFAULT_GEONAMES_USERNAME
@@ -310,6 +308,10 @@ class AstrologicalSubject:
         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.iso_formatted_utc_datetime} UTC\nBirth location: {self.city}, Lat {self.lat}, Lon {self.lng}"
 
@@ -646,6 +648,106 @@ 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
+    ) -> "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
+
+        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
+        )
+
+        return subject
 
 if __name__ == "__main__":
     import json
@@ -684,5 +786,4 @@ if __name__ == "__main__":
     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(johnny.json(dump=True, indent=2))
+    johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", perspective_type="Topocentric")

{kerykeion-4.12.0 → kerykeion-4.12.2}/kerykeion/kr_types/kr_models.py

@@ -109,6 +109,10 @@ 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]

{kerykeion-4.12.0 → kerykeion-4.12.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "kerykeion"
-version = "4.12.0"
+version = "4.12.2"
 authors = ["Giacomo Battaglia <battaglia.giacomo@yahoo.it>"]
 description = "A python library for astrology."
 license = "AGPL-3.0"