kerykeion 5.1.6__tar.gz → 5.1.7__tar.gz

{kerykeion-5.1.6 → kerykeion-5.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kerykeion
-Version: 5.1.6
+Version: 5.1.7
 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
@@ -1781,6 +1781,8 @@ Since the AstrologerAPI is an external third-party service, using it does _not_
 
 Contributions are welcome! Feel free to submit pull requests or report issues.
 
+By submitting a contribution, you agree to assign the copyright of that contribution to the maintainer. The project stays openly available under the AGPL for everyone, while the re-licensing option helps sustain future development. Your authorship remains acknowledged in the commit history and release notes.
+
 ## Citations
 
 If using Kerykeion in published or academic work, please cite as follows:

{kerykeion-5.1.6 → kerykeion-5.1.7}/README.md

@@ -1741,6 +1741,8 @@ Since the AstrologerAPI is an external third-party service, using it does _not_
 
 Contributions are welcome! Feel free to submit pull requests or report issues.
 
+By submitting a contribution, you agree to assign the copyright of that contribution to the maintainer. The project stays openly available under the AGPL for everyone, while the re-licensing option helps sustain future development. Your authorship remains acknowledged in the commit history and release notes.
+
 ## Citations
 
 If using Kerykeion in published or academic work, please cite as follows:

{kerykeion-5.1.6 → kerykeion-5.1.7}/kerykeion/astrological_subject_factory.py

@@ -59,7 +59,8 @@ from kerykeion.utilities import (
     check_and_adjust_polar_latitude,
     calculate_moon_phase,
     datetime_to_julian,
-    get_house_number
+    get_house_number,
+    normalize_zodiac_type,
 )
 from kerykeion.settings.config_constants import DEFAULT_ACTIVE_POINTS
 
@@ -67,7 +68,7 @@ from kerykeion.settings.config_constants import DEFAULT_ACTIVE_POINTS
 DEFAULT_GEONAMES_USERNAME = "century.boy"
 DEFAULT_SIDEREAL_MODE: SiderealMode = "FAGAN_BRADLEY"
 DEFAULT_HOUSES_SYSTEM_IDENTIFIER: HousesSystemIdentifier = "P"
-DEFAULT_ZODIAC_TYPE: ZodiacType = "Tropic"
+DEFAULT_ZODIAC_TYPE: ZodiacType = "Tropical"
 DEFAULT_PERSPECTIVE_TYPE: PerspectiveType = "Apparent Geocentric"
 DEFAULT_GEONAMES_CACHE_EXPIRE_AFTER_DAYS = 30
 
@@ -148,8 +149,8 @@ class ChartConfiguration:
     combinations.
 
     Attributes:
-        zodiac_type (ZodiacType): The zodiac system to use ('Tropic' or 'Sidereal').
-            Defaults to 'Tropic'.
+        zodiac_type (ZodiacType): The zodiac system to use ('Tropical' or 'Sidereal').
+            Defaults to 'Tropical'.
         sidereal_mode (Optional[SiderealMode]): The sidereal calculation mode when using
             sidereal zodiac. Only required/used when zodiac_type is 'Sidereal'.
             Defaults to None (auto-set to FAGAN_BRADLEY for sidereal).
@@ -198,14 +199,17 @@ class ChartConfiguration:
             - Logs informational message when setting default sidereal mode
         """
         # Validate zodiac type
-        if self.zodiac_type not in get_args(ZodiacType):
-            raise KerykeionException(
-                f"'{self.zodiac_type}' is not a valid zodiac type! Available types are: {get_args(ZodiacType)}"
-            )
+        try:
+            normalized_zodiac_type = normalize_zodiac_type(self.zodiac_type)
+        except ValueError as exc:
+            raise KerykeionException(str(exc)) from exc
+        else:
+            if normalized_zodiac_type != self.zodiac_type:
+                self.zodiac_type = normalized_zodiac_type
 
         # Validate sidereal mode settings
-        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.sidereal_mode and self.zodiac_type == "Tropical":
+            raise KerykeionException("You can't set a sidereal mode with a Tropical zodiac type!")
 
         if self.zodiac_type == "Sidereal":
             if not self.sidereal_mode:
@@ -475,8 +479,8 @@ class AstrologicalSubjectFactory:
                 online location lookup. Get one free at geonames.org.
             online (bool, optional): Whether to fetch location data online. If False,
                 lng, lat, and tz_str must be provided. Defaults to True.
-            zodiac_type (ZodiacType, optional): Zodiac system - 'Tropic' or 'Sidereal'.
-                Defaults to 'Tropic'.
+            zodiac_type (ZodiacType, optional): Zodiac system - 'Tropical' or 'Sidereal'.
+                Defaults to 'Tropical'.
             sidereal_mode (SiderealMode, optional): Sidereal calculation mode (e.g.,
                 'FAGAN_BRADLEY', 'LAHIRI'). Only used with zodiac_type='Sidereal'.
             houses_system_identifier (HousesSystemIdentifier, optional): House system
@@ -726,7 +730,7 @@ class AstrologicalSubjectFactory:
                 or as fallback. Defaults to 51.5074 (Greenwich).
             geonames_username (str, optional): GeoNames API username. Required when
                 online=True. Defaults to DEFAULT_GEONAMES_USERNAME.
-            zodiac_type (ZodiacType, optional): Zodiac system. Defaults to 'Tropic'.
+            zodiac_type (ZodiacType, optional): Zodiac system. Defaults to 'Tropical'.
             sidereal_mode (SiderealMode, optional): Sidereal mode when zodiac_type
                 is 'Sidereal'. Defaults to None.
             houses_system_identifier (HousesSystemIdentifier, optional): House system.
@@ -866,7 +870,7 @@ class AstrologicalSubjectFactory:
             online (bool, optional): Whether to fetch location data online.
                 Defaults to True.
             zodiac_type (ZodiacType, optional): Zodiac system to use.
-                Defaults to 'Tropic'.
+                Defaults to 'Tropical'.
             sidereal_mode (SiderealMode, optional): Sidereal calculation mode.
                 Only used when zodiac_type is 'Sidereal'. Defaults to None.
             houses_system_identifier (HousesSystemIdentifier, optional): House

{kerykeion-5.1.6 → kerykeion-5.1.7}/kerykeion/backword.py

@@ -36,6 +36,7 @@ from .chart_data_factory import ChartDataFactory
 from .charts.chart_drawer import ChartDrawer
 from .aspects import AspectsFactory
 from .settings.config_constants import DEFAULT_ACTIVE_POINTS, DEFAULT_ACTIVE_ASPECTS
+from .utilities import normalize_zodiac_type
 from .schemas.kr_models import (
     AstrologicalSubjectModel,
     CompositeSubjectModel,
@@ -74,6 +75,42 @@ LEGACY_NODE_NAMES_MAP = {
 }
 
 
+def _normalize_zodiac_type_with_warning(zodiac_type: Optional[Union[str, ZodiacType]]) -> Optional[ZodiacType]:
+    """Normalize legacy zodiac type values with deprecation warning.
+
+    Wraps the utilities.normalize_zodiac_type function and adds a deprecation
+    warning for legacy formats like "tropic" or case-insensitive variants.
+
+    Args:
+        zodiac_type: Input zodiac type (may be legacy format)
+
+    Returns:
+        Normalized ZodiacType or None if input was None
+    """
+    if zodiac_type is None:
+        return None
+
+    zodiac_str = str(zodiac_type)
+
+    # Check if this is a legacy format (case-insensitive "tropic" or non-canonical case)
+    zodiac_lower = zodiac_str.lower()
+    if zodiac_lower in ("tropic", "tropical", "sidereal") and zodiac_str not in ("Tropical", "Sidereal"):
+        # Normalize using the utilities function
+        normalized = normalize_zodiac_type(zodiac_str)
+
+        # Emit deprecation warning for legacy usage
+        warnings.warn(
+            f"Zodiac type '{zodiac_str}' is deprecated in Kerykeion v5. "
+            f"Use '{normalized}' instead.",
+            DeprecationWarning,
+            stacklevel=4,
+        )
+        return normalized
+
+    # Already in correct format or will be normalized by utilities function
+    return cast(ZodiacType, normalize_zodiac_type(zodiac_str))
+
+
 def _normalize_active_points(points: Optional[Iterable[Union[str, AstrologicalPoint]]]) -> Optional[List[AstrologicalPoint]]:
     """Best-effort normalization of legacy string active points list.
 
@@ -159,7 +196,10 @@ class AstrologicalSubject:
                 stacklevel=2,
             )
 
+        # Normalize legacy zodiac type values
+        zodiac_type = _normalize_zodiac_type_with_warning(zodiac_type)
         zodiac_type = DEFAULT_ZODIAC_TYPE if zodiac_type is None else zodiac_type
+
         houses_system_identifier = (
             DEFAULT_HOUSES_SYSTEM_IDENTIFIER if houses_system_identifier is None else houses_system_identifier
         )
@@ -352,6 +392,9 @@ class AstrologicalSubject:
         if online and resolved_geonames == DEFAULT_GEONAMES_USERNAME:
             warnings.warn(GEONAMES_DEFAULT_USERNAME_WARNING, UserWarning, stacklevel=2)
 
+        # Normalize legacy zodiac type values
+        normalized_zodiac_type = _normalize_zodiac_type_with_warning(zodiac_type)
+
         model = AstrologicalSubjectFactory.from_iso_utc_time(
             name=name,
             iso_utc_time=iso_utc_time,
@@ -362,7 +405,7 @@ class AstrologicalSubject:
             lng=float(lng),
             lat=float(lat),
             geonames_username=resolved_geonames,
-            zodiac_type=(zodiac_type or DEFAULT_ZODIAC_TYPE),  # type: ignore[arg-type]
+            zodiac_type=(normalized_zodiac_type or DEFAULT_ZODIAC_TYPE),  # type: ignore[arg-type]
             sidereal_mode=sidereal_mode,
             houses_system_identifier=(houses_system_identifier or DEFAULT_HOUSES_SYSTEM_IDENTIFIER),  # type: ignore[arg-type]
             perspective_type=(perspective_type or DEFAULT_PERSPECTIVE_TYPE),  # type: ignore[arg-type]

{kerykeion-5.1.6 → kerykeion-5.1.7}/kerykeion/charts/chart_drawer.py

@@ -78,6 +78,9 @@ from kerykeion.settings.chart_defaults import (
 from typing import List, Literal
 
 
+logger = logging.getLogger(__name__)
+
+
 class ChartDrawer:
     """
     ChartDrawer generates astrological chart visualizations as SVG files from pre-computed chart data.
@@ -315,7 +318,7 @@ class ChartDrawer:
 
         active_points_count = len(self.available_planets_setting)
         if active_points_count > 24:
-            logging.warning(
+            logger.warning(
                 "ChartDrawer detected %s active celestial points; rendering may look crowded beyond 24.",
                 active_points_count,
             )
@@ -856,7 +859,7 @@ class ChartDrawer:
         try:
             required_width = self._estimate_required_width_full()
         except Exception as e:
-            logging.debug(f"Auto-size width calculation failed: {e}")
+            logger.debug("Auto-size width calculation failed: %s", e)
             return
 
         minimum_width = self._minimum_width_for_chart_type()
@@ -1271,7 +1274,7 @@ class ChartDrawer:
             template_dict["top_left_5"] = f"{self._translate('day_of_week', 'Day of Week')}: {localized_weekday}" # type: ignore
 
             # Bottom left section
-            if self.first_obj.zodiac_type == "Tropic":
+            if self.first_obj.zodiac_type == "Tropical":
                 zodiac_info = f"{self._translate('zodiac', 'Zodiac')}: {self._translate('tropical', 'Tropical')}"
             else:
                 mode_const = "SIDM_" + self.first_obj.sidereal_mode # type: ignore
@@ -1433,7 +1436,7 @@ class ChartDrawer:
             template_dict["top_left_5"] = f"{latitude_string} / {longitude_string}"
 
             # Bottom left section
-            if self.first_obj.zodiac_type == "Tropic":
+            if self.first_obj.zodiac_type == "Tropical":
                 zodiac_info = f"{self._translate('zodiac', 'Zodiac')}: {self._translate('tropical', 'Tropical')}"
             else:
                 mode_const = "SIDM_" + self.first_obj.sidereal_mode # type: ignore
@@ -1589,7 +1592,7 @@ class ChartDrawer:
             template_dict["top_left_5"] = ""#f"{self._translate('type', 'Type')}: {self._translate(self.chart_type, self.chart_type)}"
 
             # Bottom left section
-            if self.first_obj.zodiac_type == "Tropic":
+            if self.first_obj.zodiac_type == "Tropical":
                 zodiac_info = f"{self._translate('zodiac', 'Zodiac')}: {self._translate('tropical', 'Tropical')}"
             else:
                 mode_const = "SIDM_" + self.first_obj.sidereal_mode # type: ignore
@@ -1767,7 +1770,7 @@ class ChartDrawer:
             template_dict["top_left_5"] = format_datetime_with_timezone(self.second_obj.iso_formatted_local_datetime) # type: ignore
 
             # Bottom left section
-            if self.first_obj.zodiac_type == "Tropic":
+            if self.first_obj.zodiac_type == "Tropical":
                 zodiac_info = f"{self._translate('zodiac', 'Zodiac')}: {self._translate('tropical', 'Tropical')}"
             else:
                 mode_const = "SIDM_" + self.first_obj.sidereal_mode # type: ignore
@@ -1967,7 +1970,7 @@ class ChartDrawer:
             template_dict["top_left_5"] = f"{latitude_string} / {longitude_string}"
 
             # Bottom left section
-            if self.first_obj.zodiac_type == "Tropic":
+            if self.first_obj.zodiac_type == "Tropical":
                 zodiac_info = f"{self._translate('zodiac', 'Zodiac')}: {self._translate('tropical', 'Tropical')}"
             else:
                 mode_const = "SIDM_" + self.first_obj.sidereal_mode # type: ignore
@@ -2140,7 +2143,7 @@ class ChartDrawer:
                 template_dict["top_left_5"] = f"{self._translate('type', 'Type')}: {self._translate('lunar_return', 'Lunar Return')}"
 
             # Bottom left section
-            if self.first_obj.zodiac_type == "Tropic":
+            if self.first_obj.zodiac_type == "Tropical":
                 zodiac_info = f"{self._translate('zodiac', 'Zodiac')}: {self._translate('tropical', 'Tropical')}"
             else:
                 mode_const = "SIDM_" + self.first_obj.sidereal_mode # type: ignore
@@ -2237,7 +2240,7 @@ class ChartDrawer:
 
         # return filename
 
-        logging.debug(f"Template dictionary has {len(td.model_dump())} fields")
+        logger.debug("Template dictionary includes %s fields", len(td.model_dump()))
 
         self._create_template_dictionary()
 

{kerykeion-5.1.6 → kerykeion-5.1.7}/kerykeion/ephemeris_data_factory.py

@@ -48,10 +48,19 @@ License: AGPL-3.0
 
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.schemas.kr_models import AstrologicalSubjectModel
-from kerykeion.utilities import get_houses_list, get_available_astrological_points_list
+from kerykeion.utilities import (
+    get_houses_list,
+    get_available_astrological_points_list,
+    normalize_zodiac_type,
+)
 from kerykeion.astrological_subject_factory import DEFAULT_HOUSES_SYSTEM_IDENTIFIER, DEFAULT_PERSPECTIVE_TYPE, DEFAULT_ZODIAC_TYPE
-from kerykeion.schemas import EphemerisDictModel
-from kerykeion.schemas import SiderealMode, HousesSystemIdentifier, PerspectiveType, ZodiacType
+from kerykeion.schemas import (
+    EphemerisDictModel,
+    SiderealMode,
+    HousesSystemIdentifier,
+    PerspectiveType,
+    ZodiacType,
+)
 from datetime import datetime, timedelta
 from typing import Literal, Union, List
 import logging
@@ -161,7 +170,7 @@ class EphemerisDataFactory:
         self.lng = lng
         self.tz_str = tz_str
         self.is_dst = is_dst
-        self.zodiac_type = zodiac_type
+        self.zodiac_type = normalize_zodiac_type(zodiac_type)
         self.sidereal_mode = sidereal_mode
         self.houses_system_identifier = houses_system_identifier
         self.perspective_type = perspective_type

{kerykeion-5.1.6 → kerykeion-5.1.7}/kerykeion/fetch_geonames.py

@@ -6,13 +6,16 @@ License: AGPL-3.0
 """
 
 
-import logging
+from logging import getLogger
 from datetime import timedelta
 from requests import Request
 from requests_cache import CachedSession
 from typing import Union
 
 
+logger = getLogger(__name__)
+
+
 class FetchGeonames:
     """
     Class to handle requests to the GeoNames API for location data and timezone information.
@@ -63,21 +66,21 @@ class FetchGeonames:
         params = {"lat": lat, "lng": lon, "username": self.username}
 
         prepared_request = Request("GET", self.timezone_url, params=params).prepare()
-        logging.debug(f"Requesting data from GeoName timezones: {prepared_request.url}")
+        logger.debug("GeoNames timezone lookup url=%s", prepared_request.url)
 
         try:
             response = self.session.send(prepared_request)
             response_json = response.json()
 
         except Exception as e:
-            logging.error(f"Error fetching {self.timezone_url}: {e}")
+            logger.error("GeoNames timezone request failed for %s: %s", self.timezone_url, e)
             return {}
 
         try:
             timezone_data["timezonestr"] = response_json["timezoneId"]
 
         except Exception as e:
-            logging.error(f"Error serializing data maybe wrong username? Details: {e}")
+            logger.error("GeoNames timezone payload missing expected keys: %s", e)
             return {}
 
         if hasattr(response, "from_cache"):
@@ -109,15 +112,16 @@ class FetchGeonames:
         }
 
         prepared_request = Request("GET", self.base_url, params=params).prepare()
-        logging.debug(f"Requesting data from geonames basic: {prepared_request.url}")
+        logger.debug("GeoNames search url=%s", prepared_request.url)
 
         try:
             response = self.session.send(prepared_request)
+            response.raise_for_status()
             response_json = response.json()
-            logging.debug(f"Response from GeoNames: {response_json}")
+            logger.debug("GeoNames search response: %s", response_json)
 
         except Exception as e:
-            logging.error(f"Error in fetching {self.base_url}: {e}")
+            logger.error("GeoNames search request failed for %s: %s", self.base_url, e)
             return {}
 
         try:
@@ -127,7 +131,7 @@ class FetchGeonames:
             city_data_whitout_tz["countryCode"] = response_json["geonames"][0]["countryCode"]
 
         except Exception as e:
-            logging.error(f"Error serializing data maybe wrong username? Details: {e}")
+            logger.error("GeoNames search payload missing expected keys: %s", e)
             return {}
 
         if hasattr(response, "from_cache"):
@@ -147,15 +151,16 @@ class FetchGeonames:
             timezone_response = self.__get_timezone(city_data_response["lat"], city_data_response["lng"])
 
         except Exception as e:
-            logging.error(f"Error in fetching timezone: {e}")
+            logger.error("Unable to fetch timezone details: %s", e)
             return {}
 
         return {**timezone_response, **city_data_response}
 
 
 if __name__ == "__main__":
-    from kerykeion.utilities import setup_logging
-    setup_logging(level="debug")
+    """Run a tiny demonstration when executing the module directly."""
+    from kerykeion.utilities import setup_logging as configure_logging
 
+    configure_logging("debug")
     geonames = FetchGeonames("Montichiari", "IT")
     print(geonames.get_serialized_data())

{kerykeion-5.1.6 → kerykeion-5.1.7}/kerykeion/report.py

@@ -727,8 +727,7 @@ if __name__ == "__main__":
         natal_subject.iso_formatted_local_datetime,
         "Solar",
     )
-
-    # Composite chart subject
+    # Derive a composite subject representing the pair's midpoint configuration
     composite_subject = CompositeSubjectFactory(
         natal_subject,
         partner_subject,

{kerykeion-5.1.6 → kerykeion-5.1.7}/kerykeion/schemas/kr_literals.py

@@ -5,7 +5,7 @@ This is part of Kerykeion (C) 2025 Giacomo Battaglia
 from typing import Literal
 
 
-ZodiacType = Literal["Tropic", "Sidereal"]
+ZodiacType = Literal["Tropical", "Sidereal"]
 """Literal type for Zodiac Types"""
 
 

{kerykeion-5.1.6 → kerykeion-5.1.7}/kerykeion/settings/kerykeion_settings.py

@@ -47,5 +47,5 @@ def _deep_merge(base: Mapping[str, Any], overrides: Mapping[str, Any]) -> dict[s
             merged[key] = deepcopy(value)
     return merged
 
-
+# Keep the public surface area explicit for downstream imports.
 __all__ = ["SettingsSource", "load_settings_mapping", "LANGUAGE_SETTINGS"]