Allow users to override the Swiss Ephemeris directory

Previously Stellium hard-coded ~/.stellium/ephe/ as the only location
for Swiss Ephemeris data files. That works for the common case but
breaks for portable installs (PythonPortable on D:\), read-only $HOME
environments (Docker, Lambda, shared hosts), and users who already
maintain a .se1 folder for another astrology tool and don't want a
second copy.

Add a small, layered override mechanism mirroring the convention used
by pip, cargo, pyenv, HuggingFace, and friends:

1. SwissEphemerisEngine(ephe_path=...) — explicit argument, highest
   priority.
2. STELLIUM_EPHE_PATH environment variable — no code changes needed.
3. Default ~/.stellium/ephe/ — unchanged behavior for existing users.

When a custom path is supplied Stellium uses it as-is: the directory
is not created and the bundled essentials are not copied into it.
Missing custom directories emit a stderr warning instead of crashing
so misconfiguration fails loudly at the first calculation.

Also:
- Track the currently active directory (_active_ephe_dir) so
  get_ephe_dir() and has_ephe_file() report against the override
  rather than USER_EPHE_DIR.
- Allow re-initialization against a different path; same path is a
  no-op.
- Document all three mechanisms in README.md under a new
  "Ephemeris Data Location" section.
- Add tests/test_ephemeris_paths.py covering precedence, expansion,
  no-copy semantics, has_ephe_file routing, env-var pass-through, and
  an end-to-end chart calculation against a populated custom path.

Author: claude

README.md

@@ -411,6 +411,44 @@ See `stellium --help` for full CLI documentation.
 
 ---
 
+## Ephemeris Data Location
+
+Stellium bundles enough Swiss Ephemeris data to cover **1800–2999 CE** and
+automatically copies it to `~/.stellium/ephe/` on first use, so most users
+never need to download anything. Use `stellium ephemeris download` if you
+need coverage outside that range or extra asteroid files.
+
+### Using a custom ephemeris directory
+
+You can point Stellium at any existing Swiss Ephemeris folder — handy for
+portable installs, read-only home directories (Docker, Lambda, shared
+hosts), or for reusing a folder you already maintain for another astrology
+tool. Two options, in order of precedence:
+
+```python
+# 1. Explicit argument wins over everything else
+from stellium import ChartBuilder
+from stellium.engines.ephemeris import SwissEphemerisEngine
+
+chart = (ChartBuilder.from_native(native)
+    .with_ephemeris(SwissEphemerisEngine(ephe_path=r"D:\swisseph\ephe"))
+    .calculate())
+```
+
+```bash
+# 2. Environment variable — no code changes required
+export STELLIUM_EPHE_PATH=/opt/swisseph/ephe       # macOS / Linux
+set STELLIUM_EPHE_PATH=D:\swisseph\ephe            # Windows (cmd)
+$env:STELLIUM_EPHE_PATH = "D:\swisseph\ephe"       # Windows (PowerShell)
+```
+
+When you supply a custom path Stellium uses it **as-is**: the folder is not
+created, and the bundled ephemeris files are **not** copied into it.
+Make sure it already contains every `.se1` file you need for the objects
+and date range you plan to calculate.
+
+---
+
 ## 🔍 Feature Highlights
 
 ### Zodiac Systems

src/stellium/data/paths.py

@@ -27,6 +27,12 @@
 USER_DATA_DIR = Path.home() / ".stellium"
 USER_EPHE_DIR = USER_DATA_DIR / "ephe"
 
+# Environment variable that lets users override the ephemeris directory
+# without touching code — handy for portable installs, read-only $HOME
+# environments (Docker, Lambda, shared hosts), and for reusing an existing
+# Swiss Ephemeris folder from another astrology tool.
+ENV_EPHE_PATH = "STELLIUM_EPHE_PATH"
+
 # Package data locations (using importlib.resources)
 PACKAGE_DATA_MODULE = "stellium.data"
 
@@ -41,8 +47,12 @@
     "sefstars.txt",  # Fixed stars catalog
 ]
 
-# Track whether ephemeris path has been initialized this session
+# Track whether the ephemeris path has been initialized this session, and
+# which directory is currently active. `_active_ephe_dir` is the source of
+# truth once initialization has happened — it may differ from USER_EPHE_DIR
+# when the user supplies a custom path.
 _ephe_initialized = False
+_active_ephe_dir: Path | None = None
 
 
 def get_user_data_dir() -> Path:
@@ -129,74 +139,132 @@ def _copy_bundled_ephe_files() -> int:
     return copied
 
 
-def initialize_ephemeris() -> Path:
+def _resolve_ephe_path(ephe_path: str | Path | None) -> tuple[Path, bool]:
     """
-    Initialize the ephemeris system.
-
-    This function:
-    1. Ensures the user ephe directory exists
-    2. Copies bundled ephemeris files to user directory (first run only)
-    3. Sets the Swiss Ephemeris path
+    Resolve which ephemeris directory to use, following the precedence:
 
-    Call this once at startup or before any ephemeris calculations.
+    1. Explicit ``ephe_path`` argument (highest priority)
+    2. ``STELLIUM_EPHE_PATH`` environment variable
+    3. Default ``~/.stellium/ephe/``
 
     Returns:
-        Path to the ephemeris directory being used
+        A tuple of (resolved_path, is_custom). ``is_custom`` is True when the
+        path came from an override — in that case we do not create the
+        directory, copy bundled files into it, or otherwise touch its
+        contents; we assume the caller already manages it.
+    """
+    if ephe_path is not None:
+        return Path(ephe_path).expanduser(), True
+
+    env_value = os.environ.get(ENV_EPHE_PATH, "").strip()
+    if env_value:
+        return Path(env_value).expanduser(), True
+
+    return USER_EPHE_DIR, False
+
+
+def initialize_ephemeris(ephe_path: str | Path | None = None) -> Path:
     """
-    global _ephe_initialized
+    Initialize the ephemeris system.
+
+    This function:
+    1. Resolves which ephemeris directory to use (explicit arg >
+       ``STELLIUM_EPHE_PATH`` env var > default ``~/.stellium/ephe/``)
+    2. For the default location: ensures the directory exists and copies
+       bundled ephemeris files to it (first run only)
+    3. Sets the Swiss Ephemeris path via ``swe.set_ephe_path``
 
-    if _ephe_initialized:
-        return USER_EPHE_DIR
+    When a custom path is supplied the directory is used as-is: Stellium
+    will not create it or copy its bundled files into it. This makes it
+    safe to point at an existing Swiss Ephemeris installation managed by
+    another tool, or at a read-only folder.
 
-    # Ensure user directory exists
-    ephe_dir = get_user_ephe_dir()
+    If ``initialize_ephemeris`` is called a second time with a different
+    path, the ephemeris is re-initialized against the new location.
 
-    # Copy bundled files if needed (idempotent - skips existing)
-    copied = _copy_bundled_ephe_files()
-    if copied > 0:
-        print(f"Stellium: Initialized {copied} ephemeris files in {ephe_dir}")
+    Args:
+        ephe_path: Optional override for the ephemeris directory. Accepts a
+            ``str`` or ``pathlib.Path``. If omitted, falls back to the
+            ``STELLIUM_EPHE_PATH`` environment variable, then to
+            ``~/.stellium/ephe/``.
 
-    # Set Swiss Ephemeris path
-    swe.set_ephe_path(str(ephe_dir) + os.sep)
+    Returns:
+        Path to the ephemeris directory that is now active.
+    """
+    global _ephe_initialized, _active_ephe_dir
+
+    resolved, is_custom = _resolve_ephe_path(ephe_path)
+
+    # If already initialized against the same directory, nothing to do.
+    if _ephe_initialized and _active_ephe_dir == resolved:
+        return resolved
+
+    if is_custom:
+        # Custom path: use as-is. Do not create the directory, do not copy
+        # bundled files — the caller is responsible for what lives there.
+        # We still warn (not raise) if it doesn't exist so that misconfigured
+        # paths fail loudly at the first calculation rather than silently.
+        if not resolved.exists():
+            print(
+                f"Stellium: warning — custom ephemeris path {resolved} does "
+                "not exist. Swiss Ephemeris calculations will fail until "
+                "the directory is created and populated.",
+                file=sys.stderr,
+            )
+    else:
+        # Default location: ensure the directory exists and populate it
+        # with the essential bundled files on first run.
+        resolved.mkdir(parents=True, exist_ok=True)
+        copied = _copy_bundled_ephe_files()
+        if copied > 0:
+            print(f"Stellium: Initialized {copied} ephemeris files in {resolved}")
+
+    # Set Swiss Ephemeris path (trailing separator is required by the C lib).
+    swe.set_ephe_path(str(resolved) + os.sep)
 
     _ephe_initialized = True
-    return ephe_dir
+    _active_ephe_dir = resolved
+    return resolved
 
 
 def get_ephe_dir() -> Path:
     """
     Get the ephemeris directory, initializing if necessary.
 
     This is the main function that should be used throughout the codebase
-    to get the ephemeris path.
+    to get the ephemeris path. Respects any override previously set via
+    :func:`initialize_ephemeris` or the ``STELLIUM_EPHE_PATH`` env var.
 
     Returns:
-        Path to the ephemeris directory
+        Path to the ephemeris directory currently in use.
     """
     if not _ephe_initialized:
         initialize_ephemeris()
-    return USER_EPHE_DIR
+    assert _active_ephe_dir is not None  # just initialized
+    return _active_ephe_dir
 
 
 def reset_ephe_initialization() -> None:
     """
     Reset the ephemeris initialization flag.
 
-    Useful for testing or if you need to reinitialize.
+    Useful for testing or if you need to reinitialize against a different
+    directory.
     """
-    global _ephe_initialized
+    global _ephe_initialized, _active_ephe_dir
     _ephe_initialized = False
+    _active_ephe_dir = None
 
 
 # Convenience function for checking if a specific ephemeris file exists
 def has_ephe_file(filename: str) -> bool:
     """
-    Check if a specific ephemeris file exists in the user directory.
+    Check if a specific ephemeris file exists in the active directory.
 
     Args:
         filename: Name of the ephemeris file (e.g., "se136199.se1")
 
     Returns:
-        True if the file exists
+        True if the file exists in the directory currently being used.
     """
-    return (get_user_ephe_dir() / filename).exists()
+    return (get_ephe_dir() / filename).exists()

src/stellium/engines/ephemeris.py

@@ -1,5 +1,7 @@
 """Ephemeris calculation engines."""
 
+from pathlib import Path
+
 import swisseph as swe
 
 from stellium.core.ayanamsa import ZodiacType, get_ayanamsa
@@ -16,21 +18,26 @@
 from stellium.utils.cache import cached
 
 
-def _set_ephemeris_path() -> None:
+def _set_ephemeris_path(ephe_path: str | Path | None = None) -> None:
     """
     Set the path to Swiss Ephemeris data files.
 
     This function initializes the ephemeris system by:
-    1. Ensuring the user ephe directory exists (~/.stellium/ephe/)
-    2. Copying bundled ephemeris files from the package if needed
+    1. Resolving the ephemeris directory (explicit arg >
+       ``STELLIUM_EPHE_PATH`` env var > default ``~/.stellium/ephe/``)
+    2. For the default location, copying bundled ephemeris files if needed
     3. Setting the Swiss Ephemeris path
 
-    The ephemeris files are stored in the user's home directory so that:
+    By default Stellium stores ephemeris files in the user's home directory:
     - Users can add their own asteroid ephemeris files
     - The package size stays small (only essential files bundled)
     - Updates don't overwrite user-downloaded files
+
+    Passing ``ephe_path`` (or setting ``STELLIUM_EPHE_PATH``) lets you point
+    Stellium at an existing Swiss Ephemeris folder managed by another tool,
+    at a portable-install directory, or at a read-only shared location.
     """
-    initialize_ephemeris()
+    initialize_ephemeris(ephe_path)
 
 
 # Swiss Ephemeris object IDs
@@ -116,9 +123,19 @@ class SwissEphemerisEngine:
     # This prevents repeated warnings for the same object across multiple calculations
     _warned_missing_ephemeris: set[str] = set()
 
-    def __init__(self):
-        """Initialize Swiss Ephemeris."""
-        _set_ephemeris_path()
+    def __init__(self, ephe_path: str | Path | None = None) -> None:
+        """Initialize Swiss Ephemeris.
+
+        Args:
+            ephe_path: Optional override for the Swiss Ephemeris data
+                directory. If omitted, Stellium falls back to the
+                ``STELLIUM_EPHE_PATH`` environment variable and then to the
+                default ``~/.stellium/ephe/`` location. Supplying a custom
+                path makes Stellium use that directory as-is — no files are
+                created or copied into it.
+        """
+        _set_ephemeris_path(ephe_path)
+        self._ephe_path = ephe_path
         self._object_ids = SWISS_EPHEMERIS_IDS.copy()
 
     def _get_object_type(self, name: str) -> ObjectType: