natal-chart 0.1.0__tar.gz

natal_chart-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+*.bsp

natal_chart-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - unreleased
+
+First release: planets Sun-Pluto (JPL DE440s via Skyfield), mean node, mean
+Lilith, Placidus/Koch/Porphyry/Equal/Whole Sign houses with a polar-latitude
+error or fallback, major aspects with applying/separating, transits, CLI.

natal_chart-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Balakirev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

natal_chart-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: natal-chart
+Version: 0.1.0
+Summary: Tropical natal chart math (planets, Placidus/Koch/whole-sign houses, aspects, transits) on NASA JPL ephemerides via Skyfield. No Swiss Ephemeris.
+Project-URL: Homepage, https://astralread.com
+Project-URL: Repository, https://github.com/VictorMachiavelli/natal-chart
+Project-URL: Issues, https://github.com/VictorMachiavelli/natal-chart/issues
+Author-email: Victor Balakirev <balakirevvictor@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aspects,astrology,ephemeris,horoscope,houses,jpl,natal chart,placidus,skyfield,transits
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: skyfield>=1.45
+Requires-Dist: tzdata; sys_platform == 'win32'
+Provides-Extra: test
+Requires-Dist: pyswisseph>=2.10; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# natal-chart
+
+Tropical natal chart math for Python: planet positions, houses
+(Placidus, Koch, Porphyry, Equal, Whole Sign), Ascendant/MC, mean lunar node,
+mean Black Moon Lilith, major aspects and transits.
+
+Positions come from NASA JPL ephemerides through
+[Skyfield](https://rhodesmill.org/skyfield/). The package does **not** use or
+contain the Swiss Ephemeris, so it can be released under the MIT license.
+
+## Install
+
+```bash
+pip install natal-chart
+```
+
+Requires Python 3.10+. The only dependency is Skyfield (which brings NumPy).
+
+The first call downloads the JPL DE440s ephemeris (~32 MB, covers
+1849-2150) into `~/.cache/natal-chart` (override with the `NATAL_CHART_DATA`
+environment variable). It is never bundled with the package. To use a
+different file, e.g. the smaller DE421 (1900-2050) or DE440 (1550-2650):
+
+```python
+import natal_chart
+natal_chart.set_ephemeris("de421.bsp")   # or NATAL_CHART_EPHEMERIS=de421.bsp
+```
+
+## Quickstart
+
+```python
+from natal_chart import chart, aspects, transits
+
+# Fictional birth data: local time + IANA time zone
+c = chart("1990-05-17T14:30", lat=55.75, lon=37.62, tz="Europe/Moscow")
+
+c["Sun"].sign, round(c["Sun"].degree, 2)   # ('Taurus', 26.26)
+c["Saturn"].retrograde                      # True
+c["Moon"].house                             # 5
+c.ascendant.longitude, c.mc.longitude       # 166.69..., 71.52...
+c.cusps                                     # 12 cusp longitudes, cusp 1 first
+
+for a in aspects(c)[:3]:
+    print(a.first, a.aspect, a.second, round(a.orb, 2),
+          "applying" if a.applying else "separating")
+
+for a in transits(c, "2026-11-10T12:00:00+00:00"):
+    print("transiting", a.first, a.aspect, "natal", a.second, round(a.orb, 2))
+```
+
+`chart()` accepts a timezone-aware `datetime`, or a naive one plus `tz=`.
+A naive time without `tz` is rejected rather than silently treated as UTC.
+
+Points: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune,
+Pluto, `"Mean Node"`, `"Lilith"`, `"Ascendant"`, `"MC"`. Each `Point` has
+`longitude`, `latitude`, `speed` (°/day), `sign`, `degree` (within sign),
+`retrograde` and `house`.
+
+### Aspects
+
+`aspects(chart, orbs=None, points=None)` finds conjunction, sextile, square,
+trine and opposition, tightest first. Default orbs:
+conjunction/opposition 8°, trine/square 7°, sextile 5°. Pass your own
+mapping, e.g. `orbs={"conjunction": 10, "square": 6}` (aspects left out are
+not searched). `applying` is decided from the current speeds of both points.
+
+`transits(natal, when, orbs=None)` compares the transiting planets with every
+natal point (default orb 1°). The natal point is treated as fixed.
+
+### Command line
+
+```text
+$ natal-chart 1990-05-17T14:30 --tz Europe/Moscow --lat 55.75 --lon 37.62 --aspects
+1990-05-17 10:30:00 UTC  lat 55.7500  lon 37.6200  houses: placidus
+
+Point      Sign             Degree   Longitude     Speed  R  House
+Sun        Taurus        26°15'49"     56.2636    0.9636         9
+Moon       Aquarius      21°37'13"    321.6204   12.9387         5
+...
+```
+
+Options: `--houses {placidus,koch,porphyry,equal,whole_sign}`,
+`--polar-fallback {porphyry,equal,whole_sign}`, `--aspects`,
+`--transits DATETIME`, `--json`. Without `--tz` the time is taken as UTC.
+
+## What exactly is computed
+
+* **Planets**: geocentric *apparent* positions (light-time, aberration,
+  gravitational deflection), ecliptic longitude and latitude referred to the
+  **true equinox and ecliptic of date** (IAU 2006 precession + IAU 2000A
+  nutation), tropical zodiac. This is the same convention as the default
+  output of most astrology software. Mars-Pluto use the planetary-system
+  barycenter segments of the JPL file; the offset from the planet's centre
+  is below 0.1" as seen from Earth.
+* **Speed**: central difference over ±0.01 day, degrees per day.
+* **Mean node / mean Lilith**: ELP-2000/82 mean-element polynomials
+  (Meeus, *Astronomical Algorithms*, ch. 47), plus nutation in longitude.
+  Lilith (mean lunar apogee) is projected from the inclined lunar orbit onto
+  the ecliptic, so it also has a small ecliptic latitude.
+* **Houses**: RAMC from Skyfield's Greenwich apparent sidereal time plus the
+  east longitude; true obliquity of date. Placidus is computed by iterating
+  each cusp on its own diurnal/nocturnal semi-arc; Koch from Ascendants at
+  the times that trisect the MC degree's semi-arc.
+* **Time**: from 1972 the input is UTC with leap seconds. Before 1972 the
+  given UTC is treated as UT1 (civil time followed UT then); Delta T comes
+  from Skyfield's built-in model. Ambiguous or non-existent local times at
+  DST changes follow Python's `datetime.fold` rule (`fold=0` by default).
+
+### High latitudes
+
+Placidus and Koch are undefined when part of the ecliptic never rises or sets,
+i.e. for |latitude| ≥ 90° − obliquity (about 66.56°). There `chart()` raises
+`PolarHousesError` with an explanation. Pass
+`polar_fallback="porphyry"` (or `"equal"`, `"whole_sign"`) to get a chart
+anyway; then `chart.house_system` names the system actually used and
+`chart.polar_fallback_used` is `True`. Equal, Whole Sign and Porphyry work at
+any latitude short of the poles.
+
+## Accuracy
+
+Measured against the Swiss Ephemeris 2.10 (pyswisseph, with its
+`sepl_18`/`semo_18` data files) on 300 random fictional dates 1900-2100 and
+latitudes within ±66°. The comparison is run at identical instants (same TT
+for bodies, same UT1 for houses) so that what is measured is ephemeris,
+reduction and house math, not the two libraries' Delta T models.
+
+| Quantity | Max difference |
+| --- | --- |
+| Sun ... Pluto, longitude | 0.007" |
+| Sun ... Pluto, latitude | 0.003" |
+| Speeds | 0.00008 °/day |
+| Mean Node | 0.11" |
+| Mean Lilith (longitude / latitude) | 0.54" / 0.04" |
+| Ascendant, MC | 0.000003° |
+| Placidus, Koch, Porphyry, Equal cusps | 0.000006° |
+
+Things that differ between libraries and are *not* in the table:
+
+* **Delta T for future dates.** Neither library can know future Earth
+  rotation; their predictions differ by a few seconds after 2026, which moves
+  the Moon (0.5"/s) by up to ~13" at the same civil time (we measured 0.003"
+  for 1972-2025 and 0.4" for 1900-1971).
+* **Sidereal time after 2050.** From 2050-01-01 the Swiss Ephemeris switches
+  to its own long-term sidereal-time formula, which differs from the IERS
+  expression used here by ~1.9" (0.13 s of time).
+
+The comparison test (`tests/test_vs_swisseph.py`) runs only when the
+optional `pyswisseph` dev dependency is installed; point `SE_EPHE_PATH` at the
+Swiss data files to compare against the full Swiss Ephemeris instead of its
+built-in Moshier fallback.
+
+## Ephemeris data
+
+NASA JPL DE440 (public domain) via Skyfield. Default file DE440s; the
+file is downloaded on first use and is not part of this package.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[test]"
+.venv/bin/pytest -s
+```
+
+All birth data in the tests is fictional. `pyswisseph` (AGPL) appears only in
+the optional test extra and is never imported by the package.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+Built by the team behind [AstralRead](https://astralread.com) — free natal
+chart & AI astrologer.

natal_chart-0.1.0/README.md

@@ -0,0 +1,174 @@
+# natal-chart
+
+Tropical natal chart math for Python: planet positions, houses
+(Placidus, Koch, Porphyry, Equal, Whole Sign), Ascendant/MC, mean lunar node,
+mean Black Moon Lilith, major aspects and transits.
+
+Positions come from NASA JPL ephemerides through
+[Skyfield](https://rhodesmill.org/skyfield/). The package does **not** use or
+contain the Swiss Ephemeris, so it can be released under the MIT license.
+
+## Install
+
+```bash
+pip install natal-chart
+```
+
+Requires Python 3.10+. The only dependency is Skyfield (which brings NumPy).
+
+The first call downloads the JPL DE440s ephemeris (~32 MB, covers
+1849-2150) into `~/.cache/natal-chart` (override with the `NATAL_CHART_DATA`
+environment variable). It is never bundled with the package. To use a
+different file, e.g. the smaller DE421 (1900-2050) or DE440 (1550-2650):
+
+```python
+import natal_chart
+natal_chart.set_ephemeris("de421.bsp")   # or NATAL_CHART_EPHEMERIS=de421.bsp
+```
+
+## Quickstart
+
+```python
+from natal_chart import chart, aspects, transits
+
+# Fictional birth data: local time + IANA time zone
+c = chart("1990-05-17T14:30", lat=55.75, lon=37.62, tz="Europe/Moscow")
+
+c["Sun"].sign, round(c["Sun"].degree, 2)   # ('Taurus', 26.26)
+c["Saturn"].retrograde                      # True
+c["Moon"].house                             # 5
+c.ascendant.longitude, c.mc.longitude       # 166.69..., 71.52...
+c.cusps                                     # 12 cusp longitudes, cusp 1 first
+
+for a in aspects(c)[:3]:
+    print(a.first, a.aspect, a.second, round(a.orb, 2),
+          "applying" if a.applying else "separating")
+
+for a in transits(c, "2026-11-10T12:00:00+00:00"):
+    print("transiting", a.first, a.aspect, "natal", a.second, round(a.orb, 2))
+```
+
+`chart()` accepts a timezone-aware `datetime`, or a naive one plus `tz=`.
+A naive time without `tz` is rejected rather than silently treated as UTC.
+
+Points: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune,
+Pluto, `"Mean Node"`, `"Lilith"`, `"Ascendant"`, `"MC"`. Each `Point` has
+`longitude`, `latitude`, `speed` (°/day), `sign`, `degree` (within sign),
+`retrograde` and `house`.
+
+### Aspects
+
+`aspects(chart, orbs=None, points=None)` finds conjunction, sextile, square,
+trine and opposition, tightest first. Default orbs:
+conjunction/opposition 8°, trine/square 7°, sextile 5°. Pass your own
+mapping, e.g. `orbs={"conjunction": 10, "square": 6}` (aspects left out are
+not searched). `applying` is decided from the current speeds of both points.
+
+`transits(natal, when, orbs=None)` compares the transiting planets with every
+natal point (default orb 1°). The natal point is treated as fixed.
+
+### Command line
+
+```text
+$ natal-chart 1990-05-17T14:30 --tz Europe/Moscow --lat 55.75 --lon 37.62 --aspects
+1990-05-17 10:30:00 UTC  lat 55.7500  lon 37.6200  houses: placidus
+
+Point      Sign             Degree   Longitude     Speed  R  House
+Sun        Taurus        26°15'49"     56.2636    0.9636         9
+Moon       Aquarius      21°37'13"    321.6204   12.9387         5
+...
+```
+
+Options: `--houses {placidus,koch,porphyry,equal,whole_sign}`,
+`--polar-fallback {porphyry,equal,whole_sign}`, `--aspects`,
+`--transits DATETIME`, `--json`. Without `--tz` the time is taken as UTC.
+
+## What exactly is computed
+
+* **Planets**: geocentric *apparent* positions (light-time, aberration,
+  gravitational deflection), ecliptic longitude and latitude referred to the
+  **true equinox and ecliptic of date** (IAU 2006 precession + IAU 2000A
+  nutation), tropical zodiac. This is the same convention as the default
+  output of most astrology software. Mars-Pluto use the planetary-system
+  barycenter segments of the JPL file; the offset from the planet's centre
+  is below 0.1" as seen from Earth.
+* **Speed**: central difference over ±0.01 day, degrees per day.
+* **Mean node / mean Lilith**: ELP-2000/82 mean-element polynomials
+  (Meeus, *Astronomical Algorithms*, ch. 47), plus nutation in longitude.
+  Lilith (mean lunar apogee) is projected from the inclined lunar orbit onto
+  the ecliptic, so it also has a small ecliptic latitude.
+* **Houses**: RAMC from Skyfield's Greenwich apparent sidereal time plus the
+  east longitude; true obliquity of date. Placidus is computed by iterating
+  each cusp on its own diurnal/nocturnal semi-arc; Koch from Ascendants at
+  the times that trisect the MC degree's semi-arc.
+* **Time**: from 1972 the input is UTC with leap seconds. Before 1972 the
+  given UTC is treated as UT1 (civil time followed UT then); Delta T comes
+  from Skyfield's built-in model. Ambiguous or non-existent local times at
+  DST changes follow Python's `datetime.fold` rule (`fold=0` by default).
+
+### High latitudes
+
+Placidus and Koch are undefined when part of the ecliptic never rises or sets,
+i.e. for |latitude| ≥ 90° − obliquity (about 66.56°). There `chart()` raises
+`PolarHousesError` with an explanation. Pass
+`polar_fallback="porphyry"` (or `"equal"`, `"whole_sign"`) to get a chart
+anyway; then `chart.house_system` names the system actually used and
+`chart.polar_fallback_used` is `True`. Equal, Whole Sign and Porphyry work at
+any latitude short of the poles.
+
+## Accuracy
+
+Measured against the Swiss Ephemeris 2.10 (pyswisseph, with its
+`sepl_18`/`semo_18` data files) on 300 random fictional dates 1900-2100 and
+latitudes within ±66°. The comparison is run at identical instants (same TT
+for bodies, same UT1 for houses) so that what is measured is ephemeris,
+reduction and house math, not the two libraries' Delta T models.
+
+| Quantity | Max difference |
+| --- | --- |
+| Sun ... Pluto, longitude | 0.007" |
+| Sun ... Pluto, latitude | 0.003" |
+| Speeds | 0.00008 °/day |
+| Mean Node | 0.11" |
+| Mean Lilith (longitude / latitude) | 0.54" / 0.04" |
+| Ascendant, MC | 0.000003° |
+| Placidus, Koch, Porphyry, Equal cusps | 0.000006° |
+
+Things that differ between libraries and are *not* in the table:
+
+* **Delta T for future dates.** Neither library can know future Earth
+  rotation; their predictions differ by a few seconds after 2026, which moves
+  the Moon (0.5"/s) by up to ~13" at the same civil time (we measured 0.003"
+  for 1972-2025 and 0.4" for 1900-1971).
+* **Sidereal time after 2050.** From 2050-01-01 the Swiss Ephemeris switches
+  to its own long-term sidereal-time formula, which differs from the IERS
+  expression used here by ~1.9" (0.13 s of time).
+
+The comparison test (`tests/test_vs_swisseph.py`) runs only when the
+optional `pyswisseph` dev dependency is installed; point `SE_EPHE_PATH` at the
+Swiss data files to compare against the full Swiss Ephemeris instead of its
+built-in Moshier fallback.
+
+## Ephemeris data
+
+NASA JPL DE440 (public domain) via Skyfield. Default file DE440s; the
+file is downloaded on first use and is not part of this package.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[test]"
+.venv/bin/pytest -s
+```
+
+All birth data in the tests is fictional. `pyswisseph` (AGPL) appears only in
+the optional test extra and is never imported by the package.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+Built by the team behind [AstralRead](https://astralread.com) — free natal
+chart & AI astrologer.

natal_chart-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "natal-chart"
+dynamic = ["version"]
+description = "Tropical natal chart math (planets, Placidus/Koch/whole-sign houses, aspects, transits) on NASA JPL ephemerides via Skyfield. No Swiss Ephemeris."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Victor Balakirev", email = "balakirevvictor@gmail.com" }]
+keywords = ["astrology", "natal chart", "horoscope", "ephemeris", "placidus", "houses", "aspects", "transits", "skyfield", "jpl"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Astronomy",
+    "Typing :: Typed",
+]
+dependencies = [
+    "skyfield>=1.45",
+    "tzdata; sys_platform == 'win32'",
+]
+
+[project.optional-dependencies]
+# pyswisseph (AGPL) is used ONLY by the optional cross-check tests; it is
+# never imported by the package itself.
+test = ["pytest>=7", "pyswisseph>=2.10"]
+
+[project.urls]
+Homepage = "https://astralread.com"
+Repository = "https://github.com/VictorMachiavelli/natal-chart"
+Issues = "https://github.com/VictorMachiavelli/natal-chart/issues"
+
+[project.scripts]
+natal-chart = "natal_chart.cli:main"
+
+[tool.hatch.version]
+path = "src/natal_chart/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/natal_chart"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/natal_chart", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

natal_chart-0.1.0/src/natal_chart/__init__.py

@@ -0,0 +1,42 @@
+"""natal-chart: tropical natal chart math on NASA JPL ephemerides (via Skyfield).
+
+>>> from natal_chart import chart, aspects
+>>> c = chart("1990-05-17T14:30", lat=55.75, lon=37.62, tz="Europe/Moscow")
+>>> c["Sun"].sign
+'Taurus'
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from ._ephemeris import data_dir, set_ephemeris
+from .aspects import (
+    ASPECT_ANGLES,
+    DEFAULT_ORBS,
+    DEFAULT_TRANSIT_ORBS,
+    Aspect,
+    aspects,
+    transits,
+)
+from .chart import PLANETS, Chart, Point, chart, positions
+from .houses import HOUSE_SYSTEMS, PolarHousesError
+
+__all__ = [
+    "ASPECT_ANGLES",
+    "DEFAULT_ORBS",
+    "DEFAULT_TRANSIT_ORBS",
+    "HOUSE_SYSTEMS",
+    "PLANETS",
+    "Aspect",
+    "Chart",
+    "Point",
+    "PolarHousesError",
+    "aspects",
+    "chart",
+    "data_dir",
+    "positions",
+    "set_ephemeris",
+    "transits",
+    "__version__",
+]

natal_chart-0.1.0/src/natal_chart/_angles.py

@@ -0,0 +1,69 @@
+"""Small angle helpers (degrees)."""
+
+from __future__ import annotations
+
+import math
+
+SIGNS: tuple[str, ...] = (
+    "Aries",
+    "Taurus",
+    "Gemini",
+    "Cancer",
+    "Leo",
+    "Virgo",
+    "Libra",
+    "Scorpio",
+    "Sagittarius",
+    "Capricorn",
+    "Aquarius",
+    "Pisces",
+)
+
+
+def norm360(x: float) -> float:
+    """Normalise an angle to [0, 360)."""
+    x = math.fmod(x, 360.0)
+    if x < 0:
+        x += 360.0
+    # fmod can return 360.0 for tiny negative inputs after the addition
+    return 0.0 if x >= 360.0 else x
+
+
+def norm180(x: float) -> float:
+    """Normalise an angle to [-180, 180)."""
+    return norm360(x + 180.0) - 180.0
+
+
+def sind(x: float) -> float:
+    return math.sin(math.radians(x))
+
+
+def cosd(x: float) -> float:
+    return math.cos(math.radians(x))
+
+
+def tand(x: float) -> float:
+    return math.tan(math.radians(x))
+
+
+def asind(x: float) -> float:
+    return math.degrees(math.asin(max(-1.0, min(1.0, x))))
+
+
+def atan2d(y: float, x: float) -> float:
+    return math.degrees(math.atan2(y, x))
+
+
+def sign_of(longitude: float) -> tuple[str, float]:
+    """Return (sign name, degree within sign) for an ecliptic longitude."""
+    lon = norm360(longitude)
+    idx = int(lon // 30.0)
+    return SIGNS[idx], lon - 30.0 * idx
+
+
+def format_dms(degree_in_sign: float) -> str:
+    """Format a degree within a sign as ``DD°MM'SS"``."""
+    total = int(round(degree_in_sign * 3600.0))
+    d, rem = divmod(total, 3600)
+    m, s = divmod(rem, 60)
+    return f"{d:2d}°{m:02d}'{s:02d}\""

natal_chart-0.1.0/src/natal_chart/_ephemeris.py

@@ -0,0 +1,61 @@
+"""Loading of the JPL ephemeris through Skyfield.
+
+The ephemeris file is never shipped with the package. On first use Skyfield
+downloads it into a cache directory:
+
+* ``$NATAL_CHART_DATA`` if set, otherwise
+* ``~/.cache/natal-chart``.
+
+The default file is NASA JPL DE440s (1849-2150, ~32 MB). Any other
+Skyfield-readable SPK file (for example ``de421.bsp``, 1900-2050, ~17 MB, or
+``de440.bsp``, 1550-2650, ~114 MB) can be selected with
+:func:`set_ephemeris` or the ``NATAL_CHART_EPHEMERIS`` environment variable.
+"""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from skyfield.api import Loader
+
+DEFAULT_EPHEMERIS = "de440s.bsp"
+
+_ephemeris_name: str = os.environ.get("NATAL_CHART_EPHEMERIS", DEFAULT_EPHEMERIS)
+
+
+def data_dir() -> Path:
+    """Directory where the ephemeris file is cached."""
+    env = os.environ.get("NATAL_CHART_DATA")
+    return Path(env).expanduser() if env else Path.home() / ".cache" / "natal-chart"
+
+
+@lru_cache(maxsize=1)
+def _loader() -> Loader:
+    path = data_dir()
+    path.mkdir(parents=True, exist_ok=True)
+    return Loader(str(path), verbose=False)
+
+
+@lru_cache(maxsize=1)
+def timescale() -> Any:
+    """Skyfield timescale (uses Skyfield's built-in Delta T / leap-second data)."""
+    return _loader().timescale()
+
+
+@lru_cache(maxsize=4)
+def _load(name: str) -> Any:
+    return _loader()(name)
+
+
+def ephemeris() -> Any:
+    """The currently selected JPL ephemeris, downloading it on first use."""
+    return _load(_ephemeris_name)
+
+
+def set_ephemeris(name_or_path: str) -> None:
+    """Select the SPK file to use, e.g. ``"de421.bsp"`` or a local path."""
+    global _ephemeris_name
+    _ephemeris_name = name_or_path