Merge branch 'review' into alpha/v6

Author: g-battaglia

.gitignore

@@ -85,3 +85,11 @@ sync-docs.sh
 
 # Build-time font cache for scripts/build_chart_glyphs.py (not redistributed)
 scripts/.glyph-cache/
+
+# Artifacts written to the repo root by doc-snippet harness runs
+/report.txt
+/alice_report.txt
+/chart_data.json
+/planetary_positions.csv
+/transit_charts/
+/*.svg

DEVELOPMENT.md

@@ -45,7 +45,7 @@ Kerykeion uses [poethepoet](https://github.com/nat-n/poethepoet) as a task runne
 Tests are organized in 4 tiers (each tier includes the previous):
 
 ```bash
-# Core tests (fastest, ~1750+ tests, excludes heavy parametrized suites)
+# Core tests (fastest, ~4,500 tests, excludes heavy parametrized suites)
 uv run poe test:core
 
 # Base tier (DE440s range: 1849-2150)
@@ -57,7 +57,7 @@ uv run poe test:medium
 # Extended tier (DE441 full range)
 uv run poe test:extended
 
-# All tests including online (GeoNames API)
+# All offline tests (alias for test:extended; online GeoNames tests stay excluded)
 uv run poe test:all
 
 # Run with coverage
@@ -87,7 +87,7 @@ uv run poe typecheck
 # Type checking with MyPy
 uv run poe analyze
 
-# Run all quality checks (lint + typecheck)
+# Run the full quality gate (ruff lint + mypy + pyright + full pytest suite)
 uv run poe quality
 ```
 
@@ -136,7 +136,7 @@ kerykeion/
 │   ├── secondary_progressions/      # Progressions & solar arc
 │   ├── settings/                    # Configuration & constants
 │   └── vedic/                       # Nakshatra support
-├── tests/core/                      # Test suite (59+ files)
+├── tests/core/                      # Test suite (72 files)
 ├── examples/                        # Usage examples
 ├── site/docs/                       # Documentation source (markdown)
 ├── release_notes/                   # Per-version release notes
@@ -282,7 +282,7 @@ uv sync --upgrade
 uv add "requests>=2.32.0" --upgrade
 
 # Check for outdated dependencies
-uv tree
+uv tree --outdated
 ```
 
 ## 🏗️ Building the Package

MANDATORY_EVOLUTIONS.md

@@ -82,7 +82,7 @@ HIGH was exactly this: heliacal treating every backend error as "no event").
   (libephemeris runs `heliacal_ut` through Skyfield, which raises its own
   `ValueError` subclass — round 23 discovered this).
 - Migrate every ad-hoc `getattr(ephe, "Error", …)` handler and the remaining
-  dead `except RuntimeError` site (`sun_times/utils.py:346`, left untouched in
+  dead `except RuntimeError` site (`sun_times/utils.py:368`, left untouched in
   round 23 because no harm was reproduced) to the canonical types.
 - **Runtime validation of open `str` name parameters** at public entries whose
   type is only a `Literal` at static-check time (no runtime enforcement for
@@ -120,7 +120,7 @@ different chart with only scattered log lines to explain it:
   needs a missing planetary kernel (notably the **Sun**, which needs `sepl_18.se1`)
   falls back to its **geocentric** position — returned under the planetocentric
   label, ~62° off, with only a `logging.warning`. The fallback is deliberate and
-  logged (see the comment at `astrological_subject_factory.py` ~2353), but the
+  logged (see the comment at `astrological_subject_factory.py` ~2386), but the
   point is not flagged as degraded on the returned model.
 - **Chiron / asteroids / TNOs** need `seas_18.se1`; **fixed stars** need
   `sefstars.txt`; **barycentric** perspectives need `sepl_*.se1`. These are

README.md

@@ -82,6 +82,13 @@ It is [open source](https://github.com/g-battaglia/Astrologer-API) and directly
 - [Fixed Stars](#fixed-stars)
 - [JSON Support](#json-support)
 - [Moon Phase Details](#moon-phase-details)
+- [Timing Factories](#timing-factories)
+  - [Sun Times](#sun-times)
+  - [Planetary Hours](#planetary-hours)
+  - [Void of Course Moon](#void-of-course-moon)
+  - [Lunation Finder](#lunation-finder)
+  - [Retrograde Stations](#retrograde-stations)
+  - [Sign Ingresses](#sign-ingresses)
 - [V6 Advanced Features](#v6-advanced-features)
   - [Uranian / Hamburg School Planets](#uranian--hamburg-school-planets)
   - [Essential Dignities](#essential-dignities)
@@ -111,6 +118,7 @@ It is [open source](https://github.com/g-battaglia/Astrologer-API) and directly
 - [Documentation](#documentation)
 - [Projects built with Kerykeion](#projects-built-with-kerykeion)
 - [Development](#development)
+- [Using the Swiss Ephemeris Backend (Optional)](#using-the-swiss-ephemeris-backend-optional)
 - [Integrating Kerykeion into Your Project](#integrating-kerykeion-into-your-project)
 - [License](#license)
 - [Contributing](#contributing)

TEST.md

@@ -4,7 +4,16 @@
 from kerykeion import ChartDataFactory
 from kerykeion import AstrologicalSubjectFactory
 
-now = AstrologicalSubjectFactory.from_current_time(geonames_username="century.boy")
+# Offline location (Rome): no GeoNames account needed. For online lookup,
+# pass city/nation plus your own geonames_username instead.
+now = AstrologicalSubjectFactory.from_current_time(
+    city="Rome",
+    nation="IT",
+    lng=12.4964,
+    lat=41.8933,
+    tz_str="Europe/Rome",
+    online=False,
+)
 
 # Create chart data - this calculates elements, qualities, and aspects
 chart = ChartDataFactory.create_chart_data(

examples/current_time_report.py

@@ -4,7 +4,7 @@
 from pathlib import Path
 from os import makedirs as mkdirs
 
-OUTPUT = str(Path.home() / "kerykeion_charts_output")
+OUTPUT = str(Path(__file__).parent / "output")
 THEMES = ["classic", "black-and-white", "dark", "dark-high-contrast", "light", "strawberry"]
 
 # ── Subject 1: John Lennon ──────────────────────────────────────────────────

examples/modern_chart_john_lennon.py

@@ -146,6 +146,10 @@
     }
 )
 
+# Every name accepted in ``active_points``. Unknown names (typos) must raise
+# instead of silently vanishing from the calculation loop.
+_VALID_ACTIVE_POINT_NAMES = frozenset(get_args(AstrologicalPoint))
+
 # Declarative mapping of geometrically opposite point pairs.
 # Each derived point is computed as primary.abs_pos + 180 (mod 360).
 # negate_speed/negate_dec/negate_lat control whether speed, declination and
@@ -191,10 +195,23 @@
     bid for bid in (
         getattr(ephe, "MEAN_NODE", None), getattr(ephe, "TRUE_NODE", None),
         getattr(ephe, "MEAN_APOG", None), getattr(ephe, "OSCU_APOG", None),
-        getattr(ephe, "INTP_APOG", None),
+        getattr(ephe, "INTP_APOG", None), getattr(ephe, "INTP_PERG", None),
     ) if bid is not None
 )
 
+# Point names dropped by the exclusion above (plus their derived opposites,
+# which cannot exist without their primaries). Consumers that diagnose
+# missing points (e.g. the transit factory's misconfiguration warning) use
+# this to recognize by-design absences in non-geocentric frames.
+_GEOCENTRIC_ONLY_POINT_NAMES = frozenset(
+    {
+        "Mean_North_Lunar_Node", "True_North_Lunar_Node",
+        "Mean_South_Lunar_Node", "True_South_Lunar_Node",
+        "Mean_Lilith", "True_Lilith", "Interpolated_Lilith",
+        "Mean_Priapus", "True_Priapus", "Interpolated_Perigee",
+    }
+)
+
 
 def _degenerate_center_body_id(perspective_type: Optional[str]) -> Optional[int]:
     """Body id that IS the origin of ``perspective_type``.
@@ -824,6 +841,9 @@ def from_birth_data(
                 - If invalid zodiac/sidereal mode combinations are specified
                 - If GeoNames data is missing or invalid
                 - If timezone localization fails (ambiguous DST times)
+                - If active_points contains unknown point names, or is an
+                  empty list (pass None to use the defaults). Fixed star
+                  names are redirected to active_fixed_stars with a warning.
 
         Examples:
             >>> # Basic natal chart with online location lookup
@@ -885,6 +905,16 @@ def from_birth_data(
             active_points_list: List[AstrologicalPoint] = list(DEFAULT_ACTIVE_POINTS)
         else:
             active_points_list = list(active_points)
+            if not active_points_list:
+                # An empty list means 'no filter' downstream (_should_calculate
+                # treats it as falsy), which would silently invert the caller's
+                # explicit "nothing" into a FULL chart — the exact inversion the
+                # emptied-list branches below fail loudly for. Reject it up
+                # front; None is the documented way to request the defaults.
+                raise KerykeionException(
+                    "active_points is an empty list. Pass None (or omit it) to use "
+                    "DEFAULT_ACTIVE_POINTS, or list at least one point to calculate."
+                )
             # v6: ``active_points`` is no longer a channel for fixed stars.
             # Star names that v5 accepted here (e.g. "Regulus", "Spica") are
             # redirected to the ``active_fixed_stars`` channel — with a
@@ -928,6 +958,19 @@ def from_birth_data(
                         _merged_stars.append(_star)
                 active_fixed_stars = _merged_stars
 
+            # Anything left must be a real AstrologicalPoint: an unknown name
+            # (e.g. a typo like "Sunn") would otherwise never be iterated by
+            # the calculation loop and simply vanish from the chart — a silent
+            # wrong result rather than an error.
+            _unknown_points = [p for p in active_points_list if p not in _VALID_ACTIVE_POINT_NAMES]
+            if _unknown_points:
+                raise KerykeionException(
+                    f"Unknown active_points {_unknown_points}: not valid astrological "
+                    "points (and not fixed star names, which are redirected to "
+                    "active_fixed_stars). Check the AstrologicalPoint literal in "
+                    "kerykeion.schemas.kr_literals for valid names."
+                )
+
         # The center body of the perspective has no position as seen from itself
         # (Earth in geocentric/topocentric, Sun in heliocentric, the center
         # planet in a planetocentric chart), so drop it from the active points
@@ -957,6 +1000,30 @@ def from_birth_data(
                         "one other point or omit active_points."
                     )
 
+        # Geocentric-only points (lunar nodes, Lilith/apogee variants) have no
+        # meaning in non-geocentric frames; the calculation loop drops them
+        # (see _GEOCENTRIC_ONLY_BODY_IDS). Mirror the center-body pass: give
+        # the user-facing warning here instead of a silent disappearance, and
+        # reject a list that would empty out (the 'no filter' inversion).
+        if perspective_type not in _GEO_TOPO_PERSPECTIVES:
+            _geo_only_dropped = [p for p in active_points_list if p in _GEOCENTRIC_ONLY_POINT_NAMES]
+            if _geo_only_dropped:
+                logging.warning(
+                    "Excluding %s from active_points: geocentric-only points "
+                    "(lunar nodes, Lilith/apogee variants) have no meaning in "
+                    "the %r perspective.",
+                    _geo_only_dropped,
+                    perspective_type,
+                )
+                active_points_list = [p for p in active_points_list if p not in _GEOCENTRIC_ONLY_POINT_NAMES]
+                if not active_points_list:
+                    raise KerykeionException(
+                        f"active_points contained only {_geo_only_dropped}, which are "
+                        f"geocentric-only points with no meaning in the "
+                        f"{perspective_type!r} perspective. Include at least one "
+                        "other point or omit active_points."
+                    )
+
         calc_data["active_points"] = active_points_list
 
         # Initialize configuration

kerykeion/astrological_subject_factory.py

@@ -30,7 +30,7 @@
 """
 
 import logging
-from typing import Mapping, Union, Optional, Literal, cast
+from typing import Mapping, Union, Optional, Literal, cast, get_args
 
 from kerykeion.aspects import AspectsFactory
 from kerykeion.house_comparison.house_comparison_factory import HouseComparisonFactory
@@ -153,8 +153,21 @@ def create_chart_data(
             ChartDataModel: Comprehensive chart data model
 
         Raises:
-            KerykeionException: If chart type requirements are not met
+            KerykeionException: If ``chart_type`` is not a valid ``ChartType``,
+                or if chart type requirements are not met (e.g. a missing
+                second subject for dual charts)
         """
+        # An unknown chart_type must fail here with the valid options; letting
+        # it fall through produces misleading errors ("Second subject is
+        # required for NatalFoo charts") or a late pydantic ValidationError
+        # after the full dual pipeline has already run.
+        _valid_chart_types = get_args(ChartType)
+        if chart_type not in _valid_chart_types:
+            raise KerykeionException(
+                f"Unknown chart_type {chart_type!r}. Valid chart types: "
+                f"{', '.join(_valid_chart_types)}."
+            )
+
         # Resolve per-chart-type defaults when the caller did not specify them.
         is_natal_family = chart_type in ChartDataFactory._NATAL_FAMILY_CHART_TYPES
         if active_aspects is None:

kerykeion/chart_data_factory.py

@@ -1762,9 +1762,11 @@ class ChartDrawer:  # type: ignore[no-redef]
         chart_language (KerykeionChartLanguage, optional):
             Language code for chart labels. Defaults to 'EN'.
         language_pack (dict | None, optional):
-            Additional translations merged over the bundled defaults for the
-            selected language. Useful to introduce new languages or override
-            existing labels.
+            Additional translations. For one of the bundled languages the pack
+            is merged over that language's defaults (partial packs override
+            individual labels). For a NEW language code the pack itself is the
+            language: it must be complete (clone the EN block and edit), or
+            model validation fails listing the missing fields.
         external_view (bool, optional):
             For Natal charts only: place planets outside the zodiac ring.
             Defaults to False.
@@ -2018,9 +2020,12 @@ def __init__(
             chart_language (KerykeionChartLanguage, optional):
                 Language code for chart labels (e.g., 'EN', 'IT'). Defaults to 'EN'.
             language_pack (dict | None, optional):
-                Additional translations merged over the bundled defaults for the
-                selected language. Useful to introduce new languages or override
-                existing labels.
+                Additional translations. For one of the bundled languages the
+                pack is merged over that language's defaults (partial packs
+                override individual labels). For a NEW language code the pack
+                itself is the language: it must be complete (clone the EN
+                block and edit), or model validation fails listing the
+                missing fields.
             external_view (bool, optional):
                 Whether to use external visualization (planets on outer ring) for
                 single-subject charts. Only applies to Natal charts. Defaults to False.
@@ -2061,10 +2066,34 @@ def __init__(
             show_zodiac_background_ring (bool, optional):
                 Default for whether to draw colored zodiac wedges (modern style only).
                 Can be overridden at render time.  Defaults to True.
+
+        Raises:
+            KerykeionException: If ``theme`` is not a valid KerykeionChartTheme
+                (and not None), if ``chart_language`` is not a valid
+                KerykeionChartLanguage (unless a ``language_pack`` supplies the
+                custom language), or if ``double_chart_aspect_grid_type`` is
+                not 'list' or 'table'.
         """
         # =====================================================================
         # STEP 1: Store basic configuration parameters
         # =====================================================================
+        # Validate the open string parameters up front, mirroring the theme
+        # contract below: an unknown language would otherwise silently fall
+        # back to EN and an unknown grid type would silently render as
+        # "table" — plausible-looking output hiding the caller's mistake.
+        # A language_pack legitimizes ANY code: it is the documented way to
+        # introduce new languages (e.g. chart_language="JP" + a JP pack).
+        if chart_language not in get_args(KerykeionChartLanguage) and language_pack is None:
+            raise KerykeionException(
+                f"chart_language {chart_language!r} is not available. "
+                f"Valid languages: {', '.join(get_args(KerykeionChartLanguage))} — "
+                "or supply a language_pack to introduce a custom language."
+            )
+        if double_chart_aspect_grid_type not in ("list", "table"):
+            raise KerykeionException(
+                f"double_chart_aspect_grid_type {double_chart_aspect_grid_type!r} "
+                "is not valid. Use 'list' or 'table'."
+            )
         # These are direct assignments of constructor parameters to instance
         # attributes. They form the foundation for all subsequent setup.
         self._store_basic_configuration(