kerykeion 5.0.1__tar.gz → 5.0.2__tar.gz

{kerykeion-5.0.1 → kerykeion-5.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kerykeion
-Version: 5.0.1
+Version: 5.0.2
 Summary: A Python library for astrological calculations, including natal charts, houses, planetary aspects, and SVG chart generation.
 Project-URL: Homepage, https://www.kerykeion.net/
 Project-URL: Repository, https://github.com/g-battaglia/kerykeion
@@ -92,6 +92,9 @@ Maintaining this project requires substantial time and effort. The Astrologer AP
   - [External Birth Chart](#external-birth-chart)
   - [Synastry Chart](#synastry-chart)
   - [Transit Chart](#transit-chart)
+  - [Solar Return Chart (Dual Wheel)](#solar-return-chart-dual-wheel)
+  - [Solar Return Chart (Single Wheel)](#solar-return-chart-single-wheel)
+  - [Lunar Return Chart](#lunar-return-chart)
   - [Composite Chart](#composite-chart)
 - [Wheel Only Charts](#wheel-only-charts)
   - [Birth Chart](#birth-chart-1)
@@ -99,6 +102,7 @@ Maintaining this project requires substantial time and effort. The Astrologer AP
   - [Synastry Chart](#synastry-chart-1)
   - [Change the Output Directory](#change-the-output-directory)
   - [Change Language](#change-language)
+  - [Minified SVG](#minified-svg)
   - [SVG without CSS Variables](#svg-without-css-variables)
   - [Grid Only SVG](#grid-only-svg)
 - [Report Generator](#report-generator)
@@ -224,7 +228,7 @@ from kerykeion.charts.chart_drawer import ChartDrawer
 birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 
 # Step 2: Pre-compute chart data for external natal chart
-chart_data = ChartDataFactory.create_external_natal_chart_data(birth_chart)
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
 
 # Step 3: Create visualization
 birth_chart_svg = ChartDrawer(chart_data=chart_data)
@@ -275,6 +279,104 @@ transit_chart.save_svg()
 
 ![John Lennon Transit Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Transit%20Chart.svg)
 
+### Solar Return Chart (Dual Wheel)
+
+```python
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.planetary_return_factory import PlanetaryReturnFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create natal subject
+john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+
+# Step 2: Calculate Solar Return subject (offline example with manual coordinates)
+return_factory = PlanetaryReturnFactory(
+    john,
+    lng=-2.9833,
+    lat=53.4000,
+    tz_str="Europe/London",
+    online=False
+)
+solar_return_subject = return_factory.next_return_from_year(1964, "Solar")
+
+# Step 3: Pre-compute return chart data (dual wheel: natal + solar return)
+chart_data = ChartDataFactory.create_return_chart_data(john, solar_return_subject)
+
+# Step 4: Create visualization
+solar_return_chart = ChartDrawer(chart_data=chart_data)
+solar_return_chart.save_svg()
+```
+
+![John Lennon Solar Return Chart (Dual Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20DualReturnChart%20Chart%20-%20Solar%20Return.svg)
+
+### Solar Return Chart (Single Wheel)
+
+```python
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.planetary_return_factory import PlanetaryReturnFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create natal subject
+john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+
+# Step 2: Calculate Solar Return subject (offline example with manual coordinates)
+return_factory = PlanetaryReturnFactory(
+    john,
+    lng=-2.9833,
+    lat=53.4000,
+    tz_str="Europe/London",
+    online=False
+)
+solar_return_subject = return_factory.next_return_from_year(1964, "Solar")
+
+# Step 3: Build a single-wheel return chart
+chart_data = ChartDataFactory.create_single_wheel_return_chart_data(solar_return_subject)
+
+# Step 4: Create visualization
+single_wheel_chart = ChartDrawer(chart_data=chart_data)
+single_wheel_chart.save_svg()
+```
+
+![John Lennon Solar Return Chart (Single Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20Solar%20Return%20-%20SingleReturnChart%20Chart.svg)
+
+### Lunar Return Chart
+
+```python
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.planetary_return_factory import PlanetaryReturnFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create natal subject
+john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+
+# Step 2: Calculate Lunar Return subject
+return_factory = PlanetaryReturnFactory(
+    john,
+    lng=-2.9833,
+    lat=53.4000,
+    tz_str="Europe/London",
+    online=False
+)
+lunar_return_subject = return_factory.next_return_from_year(1964, "Lunar")
+
+# Step 3: Build a dual wheel (natal + lunar return)
+lunar_return_chart_data = ChartDataFactory.create_return_chart_data(john, lunar_return_subject)
+dual_wheel_chart = ChartDrawer(chart_data=lunar_return_chart_data)
+dual_wheel_chart.save_svg()
+
+# Optional: create a single-wheel lunar return
+single_wheel_data = ChartDataFactory.create_single_wheel_return_chart_data(lunar_return_subject)
+single_wheel_chart = ChartDrawer(chart_data=single_wheel_data)
+single_wheel_chart.save_svg()
+```
+
+![John Lennon Lunar Return Chart (Dual Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20DualReturnChart%20Chart%20-%20Lunar%20Return.svg)
+
+![John Lennon Lunar Return Chart (Single Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20Lunar%20Return%20-%20SingleReturnChart%20Chart.svg)
+
 ### Composite Chart
 
 ```python
@@ -336,7 +438,7 @@ from kerykeion.charts.chart_drawer import ChartDrawer
 birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 
 # Step 2: Pre-compute external natal chart data
-chart_data = ChartDataFactory.create_external_natal_chart_data(birth_chart)
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
 
 # Step 3: Create visualization
 birth_chart_svg = ChartDrawer(chart_data=chart_data)
@@ -411,6 +513,7 @@ birth_chart_svg = ChartDrawer(
     chart_language="IT"  # Change to Italian
 )
 birth_chart_svg.save_svg()
+```
 
 You can also provide custom labels (or introduce a brand-new language) by passing
 a dictionary to `language_pack`. Only the keys you supply are merged on top of the
@@ -430,7 +533,6 @@ birth_chart_svg = ChartDrawer(
     language_pack=custom_labels["PT"],
 )
 ```
-```
 
 More details [here](https://www.kerykeion.net/docs/chart-language).
 

{kerykeion-5.0.1 → kerykeion-5.0.2}/README.md

@@ -52,6 +52,9 @@ Maintaining this project requires substantial time and effort. The Astrologer AP
   - [External Birth Chart](#external-birth-chart)
   - [Synastry Chart](#synastry-chart)
   - [Transit Chart](#transit-chart)
+  - [Solar Return Chart (Dual Wheel)](#solar-return-chart-dual-wheel)
+  - [Solar Return Chart (Single Wheel)](#solar-return-chart-single-wheel)
+  - [Lunar Return Chart](#lunar-return-chart)
   - [Composite Chart](#composite-chart)
 - [Wheel Only Charts](#wheel-only-charts)
   - [Birth Chart](#birth-chart-1)
@@ -59,6 +62,7 @@ Maintaining this project requires substantial time and effort. The Astrologer AP
   - [Synastry Chart](#synastry-chart-1)
   - [Change the Output Directory](#change-the-output-directory)
   - [Change Language](#change-language)
+  - [Minified SVG](#minified-svg)
   - [SVG without CSS Variables](#svg-without-css-variables)
   - [Grid Only SVG](#grid-only-svg)
 - [Report Generator](#report-generator)
@@ -184,7 +188,7 @@ from kerykeion.charts.chart_drawer import ChartDrawer
 birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 
 # Step 2: Pre-compute chart data for external natal chart
-chart_data = ChartDataFactory.create_external_natal_chart_data(birth_chart)
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
 
 # Step 3: Create visualization
 birth_chart_svg = ChartDrawer(chart_data=chart_data)
@@ -235,6 +239,104 @@ transit_chart.save_svg()
 
 ![John Lennon Transit Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Transit%20Chart.svg)
 
+### Solar Return Chart (Dual Wheel)
+
+```python
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.planetary_return_factory import PlanetaryReturnFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create natal subject
+john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+
+# Step 2: Calculate Solar Return subject (offline example with manual coordinates)
+return_factory = PlanetaryReturnFactory(
+    john,
+    lng=-2.9833,
+    lat=53.4000,
+    tz_str="Europe/London",
+    online=False
+)
+solar_return_subject = return_factory.next_return_from_year(1964, "Solar")
+
+# Step 3: Pre-compute return chart data (dual wheel: natal + solar return)
+chart_data = ChartDataFactory.create_return_chart_data(john, solar_return_subject)
+
+# Step 4: Create visualization
+solar_return_chart = ChartDrawer(chart_data=chart_data)
+solar_return_chart.save_svg()
+```
+
+![John Lennon Solar Return Chart (Dual Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20DualReturnChart%20Chart%20-%20Solar%20Return.svg)
+
+### Solar Return Chart (Single Wheel)
+
+```python
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.planetary_return_factory import PlanetaryReturnFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create natal subject
+john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+
+# Step 2: Calculate Solar Return subject (offline example with manual coordinates)
+return_factory = PlanetaryReturnFactory(
+    john,
+    lng=-2.9833,
+    lat=53.4000,
+    tz_str="Europe/London",
+    online=False
+)
+solar_return_subject = return_factory.next_return_from_year(1964, "Solar")
+
+# Step 3: Build a single-wheel return chart
+chart_data = ChartDataFactory.create_single_wheel_return_chart_data(solar_return_subject)
+
+# Step 4: Create visualization
+single_wheel_chart = ChartDrawer(chart_data=chart_data)
+single_wheel_chart.save_svg()
+```
+
+![John Lennon Solar Return Chart (Single Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20Solar%20Return%20-%20SingleReturnChart%20Chart.svg)
+
+### Lunar Return Chart
+
+```python
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.planetary_return_factory import PlanetaryReturnFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create natal subject
+john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+
+# Step 2: Calculate Lunar Return subject
+return_factory = PlanetaryReturnFactory(
+    john,
+    lng=-2.9833,
+    lat=53.4000,
+    tz_str="Europe/London",
+    online=False
+)
+lunar_return_subject = return_factory.next_return_from_year(1964, "Lunar")
+
+# Step 3: Build a dual wheel (natal + lunar return)
+lunar_return_chart_data = ChartDataFactory.create_return_chart_data(john, lunar_return_subject)
+dual_wheel_chart = ChartDrawer(chart_data=lunar_return_chart_data)
+dual_wheel_chart.save_svg()
+
+# Optional: create a single-wheel lunar return
+single_wheel_data = ChartDataFactory.create_single_wheel_return_chart_data(lunar_return_subject)
+single_wheel_chart = ChartDrawer(chart_data=single_wheel_data)
+single_wheel_chart.save_svg()
+```
+
+![John Lennon Lunar Return Chart (Dual Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20DualReturnChart%20Chart%20-%20Lunar%20Return.svg)
+
+![John Lennon Lunar Return Chart (Single Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20Lunar%20Return%20-%20SingleReturnChart%20Chart.svg)
+
 ### Composite Chart
 
 ```python
@@ -296,7 +398,7 @@ from kerykeion.charts.chart_drawer import ChartDrawer
 birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 
 # Step 2: Pre-compute external natal chart data
-chart_data = ChartDataFactory.create_external_natal_chart_data(birth_chart)
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
 
 # Step 3: Create visualization
 birth_chart_svg = ChartDrawer(chart_data=chart_data)
@@ -371,6 +473,7 @@ birth_chart_svg = ChartDrawer(
     chart_language="IT"  # Change to Italian
 )
 birth_chart_svg.save_svg()
+```
 
 You can also provide custom labels (or introduce a brand-new language) by passing
 a dictionary to `language_pack`. Only the keys you supply are merged on top of the
@@ -390,7 +493,6 @@ birth_chart_svg = ChartDrawer(
     language_pack=custom_labels["PT"],
 )
 ```
-```
 
 More details [here](https://www.kerykeion.net/docs/chart-language).
 

{kerykeion-5.0.1 → kerykeion-5.0.2}/TODO.md

@@ -39,7 +39,8 @@
 - [~] Full documentation for the library
 - [ ] Fix: Spica glif
 - [ ] Fix: Dual charts
-- [ ] Doc snippets
+- [ ] Doc snippets check and fix
+- [ ] docs: Return charts
 
 ### 🟧 Medium Priority
 

{kerykeion-5.0.1 → kerykeion-5.0.2}/kerykeion/charts/chart_drawer.py

@@ -1071,24 +1071,28 @@ class ChartDrawer:
             return f"{synastry_label}: {name1} {and_word} {name2}"
 
         elif self.chart_type == "DualReturnChart":
-            year = datetime.fromisoformat(self.second_obj.iso_formatted_local_datetime).year # type: ignore
+            return_datetime = datetime.fromisoformat(self.second_obj.iso_formatted_local_datetime) # type: ignore
+            year = return_datetime.year
+            month_year = return_datetime.strftime("%m/%Y")
             truncated_name = self._truncate_name(self.first_obj.name)
             if self.second_obj is not None and isinstance(self.second_obj, PlanetReturnModel) and self.second_obj.return_type == "Solar":
                 solar_label = self._translate("solar_return", "Solar")
                 return f"{truncated_name} - {solar_label} {year}"
             else:
                 lunar_label = self._translate("lunar_return", "Lunar")
-                return f"{truncated_name} - {lunar_label} {year}"
+                return f"{truncated_name} - {lunar_label} {month_year}"
 
         elif self.chart_type == "SingleReturnChart":
-            year = datetime.fromisoformat(self.first_obj.iso_formatted_local_datetime).year # type: ignore
+            return_datetime = datetime.fromisoformat(self.first_obj.iso_formatted_local_datetime) # type: ignore
+            year = return_datetime.year
+            month_year = return_datetime.strftime("%m/%Y")
             truncated_name = self._truncate_name(self.first_obj.name)
             if isinstance(self.first_obj, PlanetReturnModel) and self.first_obj.return_type == "Solar":
                 solar_label = self._translate("solar_return", "Solar")
                 return f"{truncated_name} - {solar_label} {year}"
             else:
                 lunar_label = self._translate("lunar_return", "Lunar")
-                return f"{truncated_name} - {lunar_label} {year}"
+                return f"{truncated_name} - {lunar_label} {month_year}"
 
         # Fallback for unknown chart types
         return self._truncate_name(self.first_obj.name)

{kerykeion-5.0.1 → kerykeion-5.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kerykeion"
-version = "5.0.1"
+version = "5.0.2"
 authors = [
     { name = "Giacomo Battaglia", email = "kerykeion.astrology@gmail.com" }
 ]

{kerykeion-5.0.1 → kerykeion-5.0.2}/scripts/regenerate_test_charts.py

@@ -373,6 +373,22 @@ black_and_white_single_return_chart.save_svg(
     filename="John Lennon Solar Return - Black and White Theme - SingleReturnChart Chart",
 )
 
+# Lunar Return Charts
+lunar_return = return_factory.next_return_from_iso_formatted_time(
+    "2025-01-09T18:30:00+01:00",
+    return_type="Lunar",
+)
+
+# Dual Return (Natal + Lunar Return)
+lunar_dual_return_chart_data = ChartDataFactory.create_return_chart_data(first, lunar_return)
+lunar_dual_return_chart = ChartDrawer(lunar_dual_return_chart_data)
+lunar_dual_return_chart.save_svg(output_path=OUTPUT_DIR_STR)
+
+# Single Wheel Lunar Return
+lunar_single_return_chart_data = ChartDataFactory.create_single_wheel_return_chart_data(lunar_return)
+lunar_single_return_chart = ChartDrawer(lunar_single_return_chart_data)
+lunar_single_return_chart.save_svg(output_path=OUTPUT_DIR_STR)
+
 ## Transparent Background
 transparent_background_subject = AstrologicalSubjectFactory.from_birth_data("John Lennon - Transparent Background", 1940, 10, 9, 18, 30, "Liverpool", "GB", suppress_geonames_warning=True)
 transparent_background_chart_data = ChartDataFactory.create_natal_chart_data(transparent_background_subject)