kerykeion 5.0.0b1__py3-none-any.whl → 5.0.0b4__py3-none-any.whl

kerykeion/settings/translations.py

@@ -0,0 +1,74 @@
+"""
+Simple helpers to access chart translation strings.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from copy import deepcopy
+from typing import Any, Optional, TypeVar
+
+from .translation_strings import LANGUAGE_SETTINGS
+
+T = TypeVar("T")
+
+_SENTINEL = object()
+
+
+def load_language_settings(overrides: Optional[Mapping[str, Any]] = None) -> dict[str, dict[str, Any]]:
+    """Return the available language settings merged with optional overrides."""
+    languages = deepcopy(LANGUAGE_SETTINGS)
+    if overrides:
+        data = overrides.get("language_settings", overrides)
+        languages = _deep_merge(languages, data)
+    return languages
+
+
+def get_translations(
+    value: str,
+    default: T,
+    *,
+    language: Optional[str] = None,
+    language_dict: Optional[Mapping[str, Any]] = None,
+) -> T:
+    """Fetch a translation by key, falling back to English when missing."""
+    primary = _select_language(language_dict, language)
+    result = _deep_get(primary, value)
+    if result is _SENTINEL:
+        fallback = LANGUAGE_SETTINGS.get("EN", {})
+        result = _deep_get(fallback, value)
+    return default if result is _SENTINEL or result is None else result  # type: ignore[return-value]
+
+
+def _select_language(language_dict: Optional[Mapping[str, Any]], language: Optional[str]) -> Mapping[str, Any]:
+    if language_dict is not None:
+        return language_dict
+    fallback = LANGUAGE_SETTINGS.get("EN", {})
+    if language is None:
+        return fallback
+    return LANGUAGE_SETTINGS.get(language, fallback)
+
+
+def _deep_merge(base: Mapping[str, Any], overrides: Mapping[str, Any]) -> dict[str, Any]:
+    merged: dict[str, Any] = {}
+    for key, value in base.items():
+        merged[key] = deepcopy(value)
+    for key, value in overrides.items():
+        if key in merged and isinstance(merged[key], Mapping) and isinstance(value, Mapping):
+            merged[key] = _deep_merge(merged[key], value)
+        else:
+            merged[key] = deepcopy(value)
+    return merged
+
+
+def _deep_get(mapping: Mapping[str, Any], dotted_key: str):
+    current: Any = mapping
+    for segment in dotted_key.split("."):
+        if isinstance(current, Mapping) and segment in current:
+            current = current[segment]
+        else:
+            return _SENTINEL
+    return current
+
+
+__all__ = ["get_translations", "load_language_settings"]

kerykeion/transits_time_range_factory.py

@@ -55,7 +55,7 @@ Copyright: (C) 2025 Kerykeion Project
 License: AGPL-3.0
 """
 
-from typing import Union, List
+from typing import Union, List, Optional
 from datetime import datetime, timedelta
 from kerykeion.schemas.kr_models import AstrologicalSubjectModel
 from kerykeion.astrological_subject_factory import AstrologicalSubjectFactory
@@ -97,6 +97,8 @@ class TransitsTimeRangeFactory:
         settings_file (Union[Path, KerykeionSettingsModel, dict, None], optional):
             Configuration settings for calculations. Can be a file path, settings
             model, dictionary, or None for defaults. Defaults to None.
+        axis_orb_limit (float | None, optional): Optional orb threshold applied to chart axes
+            during single-chart aspect calculations. Dual-chart calculations ignore this value.
 
     Attributes:
         natal_chart: The reference natal chart for transit calculations.
@@ -104,6 +106,7 @@ class TransitsTimeRangeFactory:
         active_points: Celestial bodies included in calculations.
         active_aspects: Aspect types considered for analysis.
         settings_file: Configuration settings for the calculations.
+        axis_orb_limit: Optional orb override used when calculating single-chart aspects.
 
     Examples:
         Basic transit calculation:
@@ -137,6 +140,8 @@ class TransitsTimeRangeFactory:
         active_points: List[AstrologicalPoint] = DEFAULT_ACTIVE_POINTS,
         active_aspects: List[ActiveAspect] = DEFAULT_ACTIVE_ASPECTS,
         settings_file: Union[Path, KerykeionSettingsModel, dict, None] = None,
+        *,
+        axis_orb_limit: Optional[float] = None,
     ):
         """
         Initialize the TransitsTimeRangeFactory with calculation parameters.
@@ -161,6 +166,8 @@ class TransitsTimeRangeFactory:
             settings_file (Union[Path, KerykeionSettingsModel, dict, None], optional):
                 Configuration settings for orb tolerances, calculation methods, and
                 other parameters. Defaults to None (uses system defaults).
+            axis_orb_limit (float | None, optional): Optional orb threshold for
+                chart axes applied during aspect calculations.
 
         Note:
             - All ephemeris data points should use the same coordinate system as the natal chart
@@ -172,6 +179,7 @@ class TransitsTimeRangeFactory:
         self.active_points = active_points
         self.active_aspects = active_aspects
         self.settings_file = settings_file
+        self.axis_orb_limit = axis_orb_limit
 
     def get_transit_moments(self) -> TransitsTimeRangeModel:
         """
@@ -238,6 +246,7 @@ class TransitsTimeRangeFactory:
                 self.natal_chart,
                 active_points=self.active_points,
                 active_aspects=self.active_aspects,
+                axis_orb_limit=self.axis_orb_limit,
             ).relevant_aspects
 
             # Create a transit moment for this point in time