kerykeion 4.12.1__tar.gz → 4.12.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kerykeion
-Version: 4.12.1
+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.1 → 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.1 → kerykeion-4.12.2}/kerykeion/astrological_subject.py

@@ -36,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()
 
 
@@ -190,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
@@ -687,6 +684,71 @@ class AstrologicalSubject:
 
         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
     from kerykeion.utilities import setup_logging
@@ -724,8 +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 the utc time
-    print(johnny.utc_time)
-    print(johnny.local_time)
+    johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US", perspective_type="Topocentric")

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

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