kerykeion 4.12.1__tar.gz → 4.12.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kerykeion
-Version: 4.12.1
+Version: 4.12.3
 Summary: A python library for astrology.
 Home-page: https://www.kerykeion.net/
 License: AGPL-3.0
@@ -95,9 +95,11 @@ Kerykeion is a _Python 3.9_ package, make sure you have _Python 3.9_ or above in
 pip3 install kerykeion
 ```
 
-## Usage
+## Basic Usage
 
-Here some examples:
+The basic usage of the library is to create an instance of the AstrologicalSubject class and then access the properties of the instance to get the astrological information about the subject.
+
+Here's an example:
 
 ```python
 
@@ -105,8 +107,8 @@ Here some examples:
 from kerykeion import AstrologicalSubject
 
 # Create a kerykeion instance:
-# Args: Name, year, month, day, hour, minuts, city, nation(optional)
-kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta")
+# Args: Name, year, month, day, hour, minuts, city, nation
+kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta", "US")
 
 # Get the information about the sun in the chart:
 # (The position of the planets always starts at 0)
@@ -139,6 +141,23 @@ If you omit the nation, it will be set to "GB" by default, but the value is not
 
 ## Generate a SVG Chart
 
+### Birth Chart
+
+```python
+from kerykeion import AstrologicalSubject, KerykeionChartSVG
+
+
+birth_chart = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta", "US")
+birth_chart_svg = KerykeionChartSVG(birth_chart)
+
+birth_chart_svg.makeSVG()
+```
+
+The SVG file will be saved in the home directory.
+![John Lennon Birth Chart](https://www.kerykeion.net/assets/img/examples/birth-chart.svg)
+
+### Synastry Chart
+
 ```python
 from kerykeion import AstrologicalSubject, KerykeionChartSVG
 
@@ -153,7 +172,9 @@ 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:
+### Change the output directory
+
+By default the output directory is the home directory, you can change it by passing the new_output_directory parameter to the KerykeionChartSVG class:
 
 ```python
 from kerykeion import AstrologicalSubject, KerykeionChartSVG
@@ -161,7 +182,7 @@ from kerykeion import AstrologicalSubject, KerykeionChartSVG
 first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
 
-# Synastry Chart
+# Set the output directory to the current directory
 synastry_chart = KerykeionChartSVG(first, "Synastry", second, new_output_directory=".")
 synastry_chart.makeSVG()
 ```
@@ -179,7 +200,7 @@ To print a report of all the data:
 ```python
 from kerykeion import Report, AstrologicalSubject
 
-kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta")
+kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta", "US")
 report = Report(kanye)
 report.print_report()
 
@@ -236,14 +257,14 @@ 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:
 
 from kerykeion import SynastryAspects, AstrologicalSubject
-first = AstrologicalSubject("Jack", 1990, 6, 15, 15, 15, "Roma")
-second = AstrologicalSubject("Jane", 1991, 10, 25, 21, 00, "Roma")
+first = AstrologicalSubject("Jack", 1990, 6, 15, 15, 15, "Roma", "IT")
+second = AstrologicalSubject("Jane", 1991, 10, 25, 21, 00, "Roma", "IT")
 
 name = SynastryAspects(first, second)
 aspect_list = name.get_relevant_aspects()
@@ -257,7 +278,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 +291,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 +306,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 +318,28 @@ 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
+subject = 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.3}/README.md

@@ -58,9 +58,11 @@ Kerykeion is a _Python 3.9_ package, make sure you have _Python 3.9_ or above in
 pip3 install kerykeion
 ```
 
-## Usage
+## Basic Usage
 
-Here some examples:
+The basic usage of the library is to create an instance of the AstrologicalSubject class and then access the properties of the instance to get the astrological information about the subject.
+
+Here's an example:
 
 ```python
 
@@ -68,8 +70,8 @@ Here some examples:
 from kerykeion import AstrologicalSubject
 
 # Create a kerykeion instance:
-# Args: Name, year, month, day, hour, minuts, city, nation(optional)
-kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta")
+# Args: Name, year, month, day, hour, minuts, city, nation
+kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta", "US")
 
 # Get the information about the sun in the chart:
 # (The position of the planets always starts at 0)
@@ -102,6 +104,23 @@ If you omit the nation, it will be set to "GB" by default, but the value is not
 
 ## Generate a SVG Chart
 
+### Birth Chart
+
+```python
+from kerykeion import AstrologicalSubject, KerykeionChartSVG
+
+
+birth_chart = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta", "US")
+birth_chart_svg = KerykeionChartSVG(birth_chart)
+
+birth_chart_svg.makeSVG()
+```
+
+The SVG file will be saved in the home directory.
+![John Lennon Birth Chart](https://www.kerykeion.net/assets/img/examples/birth-chart.svg)
+
+### Synastry Chart
+
 ```python
 from kerykeion import AstrologicalSubject, KerykeionChartSVG
 
@@ -116,7 +135,9 @@ 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:
+### Change the output directory
+
+By default the output directory is the home directory, you can change it by passing the new_output_directory parameter to the KerykeionChartSVG class:
 
 ```python
 from kerykeion import AstrologicalSubject, KerykeionChartSVG
@@ -124,7 +145,7 @@ from kerykeion import AstrologicalSubject, KerykeionChartSVG
 first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
 
-# Synastry Chart
+# Set the output directory to the current directory
 synastry_chart = KerykeionChartSVG(first, "Synastry", second, new_output_directory=".")
 synastry_chart.makeSVG()
 ```
@@ -142,7 +163,7 @@ To print a report of all the data:
 ```python
 from kerykeion import Report, AstrologicalSubject
 
-kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta")
+kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta", "US")
 report = Report(kanye)
 report.print_report()
 
@@ -199,14 +220,14 @@ 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:
 
 from kerykeion import SynastryAspects, AstrologicalSubject
-first = AstrologicalSubject("Jack", 1990, 6, 15, 15, 15, "Roma")
-second = AstrologicalSubject("Jane", 1991, 10, 25, 21, 00, "Roma")
+first = AstrologicalSubject("Jack", 1990, 6, 15, 15, 15, "Roma", "IT")
+second = AstrologicalSubject("Jane", 1991, 10, 25, 21, 00, "Roma", "IT")
 
 name = SynastryAspects(first, second)
 aspect_list = name.get_relevant_aspects()
@@ -220,7 +241,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 +254,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 +269,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 +281,28 @@ 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
+subject = 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.3}/kerykeion/astrological_subject.py

@@ -34,8 +34,19 @@ from typing import Union, get_args
 
 DEFAULT_GEONAMES_USERNAME = "century.boy"
 DEFAULT_SIDEREAL_MODE = "FAGAN_BRADLEY"
-DEFAULT_HOUSES_SYSTEM = "P"
-PERSPECTIVE_TYPE = "Apparent Geocentric"
+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()
 
 
@@ -154,12 +165,12 @@ class AstrologicalSubject:
         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,
         disable_chiron: bool = False,
         sidereal_mode: Union[SiderealMode, None] = None,
-        houses_system_identifier: HousesSystemIdentifier = DEFAULT_HOUSES_SYSTEM,
-        perspective_type: PerspectiveType = PERSPECTIVE_TYPE
+        houses_system_identifier: HousesSystemIdentifier = DEFAULT_HOUSES_SYSTEM_IDENTIFIER,
+        perspective_type: PerspectiveType = DEFAULT_PERSPECTIVE_TYPE
     ) -> None:
         logging.debug("Starting Kerykeion")
 
@@ -190,20 +201,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 +685,96 @@ 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,
+        zodiac_type: ZodiacType = DEFAULT_ZODIAC_TYPE,
+        disable_chiron: 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 (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.
+            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,
+            disable_chiron=disable_chiron,
+            sidereal_mode=sidereal_mode,
+            houses_system_identifier=houses_system_identifier,
+            perspective_type=perspective_type
+        )
+
+        return subject
+
 if __name__ == "__main__":
     import json
     from kerykeion.utilities import setup_logging
@@ -724,8 +812,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.3}/pyproject.toml

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