Guide de Migration

Ce guide vous aide à mettre à niveau Ketu entre les versions majeures et mineures. Pour la liste complète des changements, consultez le Changelog.

Mise à niveau de v1.2 vers v1.3

Changement incompatible : l’axe des corps de CHART_DTYPE passe de 13 à 14 corps (D-08)

Dans v1.3, Chiron est ajouté avec body_id=13 (le 14e corps). Ce changement étend plusieurs dimensions de tableaux :

Avant (v1.2) :

chart["body_lons"] — forme (13,)
chart["body_lats"] — forme (13,)
chart["body_speeds"] — forme (13,)
chart["aspect_matrix"] — forme (13, 13)
chart["aspect_orbs"] — forme (13, 13)
SYNASTRY_BODY_COUNT = 15 (13 corps + ASC + MC)

Après (v1.3) :

chart["body_lons"] — forme (14,) — indice 13 = Chiron
chart["body_lats"] — forme (14,)
chart["body_speeds"] — forme (14,)
chart["aspect_matrix"] — forme (14, 14)
chart["aspect_orbs"] — forme (14, 14)
SYNASTRY_BODY_COUNT = 16 (14 corps + ASC + MC)

Actions de migration :

Code qui itère sur range(13) dans les tableaux de corps : mettez à jour vers range(14) ou utilisez len(chart["body_lons"]).
Tableaux CHART_DTYPE mis en cache depuis v1.2 : ils sont incompatibles. Recalculez-les avec v1.3.
Consommateurs vérifiant le nombre de corps : mettez à jour toute assertion codée en dur sur 13 ou SYNASTRY_BODY_COUNT == 15.
Indice 12 (précédemment dernier corps = Lilith) : reste inchangé — Chiron est à l’indice 13.

# Before (v1.2) — iterating over bodies
for i in range(13):
    lon = chart["body_lons"][i]

# After (v1.3) — use len() or the constant 14
for i in range(len(chart["body_lons"])):   # 14 bodies
    lon = chart["body_lons"][i]
    # i == 13 is Chiron (new)

Nouveau : accès à Chiron

Aucun nouvel import nécessaire — utilisez les fonctions de calcul existantes avec body_id=13 :

from ketu.calculations import long, lat

chiron_lon = long(jd, 13)   # Chiron longitude
chiron_lat = lat(jd, 13)    # Chiron latitude

Plage de dates valide : 1900–2100 (étendue en v1.4). Toute entrée hors plage est silencieusement clampée à la limite de segment la plus proche — aucune ValueError n’est levée.

Mise à niveau de v1.1 vers v1.2

Nouveaux Sous-paquets

v1.2 ajoute cinq nouveaux sous-paquets. Aucune API existante n’a été supprimée ni renommée.

ketu.charts — thème natal complet :

from ketu.charts import compute_chart, is_day_chart, CHART_DTYPE

chart = compute_chart(jd, lat=48.8566, lon=2.3522, system="placidus")
# chart["body_lons"][0] — Sun longitude
# chart["asc"]          — Ascendant

ketu.synastry — aspects inter-thèmes :

from ketu.synastry import calculate_synastry, SYNASTRY_DTYPE

syn = calculate_synastry(chart_a, chart_b)

ketu.composite — thème composite par point médian :

from ketu.composite import calculate_composite, circular_midpoint

comp = calculate_composite(chart_a, chart_b)

ketu.returns — retours solaires et lunaires :

from ketu.returns import solar_return, lunar_return

sr = solar_return(natal_jd, natal_lat, natal_lon, target_year=2026)
lr = lunar_return(natal_jd, natal_lat, natal_lon, target_jd=search_jd)

ketu.parts — Parties arabes :

from ketu.parts import calculate_part, calculate_all_parts

fortune = calculate_part("fortune", chart)

Systèmes de Maisons Supplémentaires

Trois nouveaux systèmes ajoutés à ketu.houses :

"whole_sign" — chaque maison = un signe zodiacal entier
"equal" — divisions égales de 30° depuis l’ASC
"regiomontanus" — division de l’équateur céleste

from ketu.houses import calculate_houses

h = calculate_houses(jd, lat, lon, system="whole_sign")

Mise à niveau de v1.0 vers v1.1

Nouveau : Ensembles d’Aspects Configurables

calculate_aspects accepte désormais un paramètre optionnel aspects. Lors de son introduction en v1.1, la valeur par défaut était EXTENDED (les 14 aspects). À partir de v1.3, la valeur par défaut de la bibliothèque est TRADITIONAL (7 aspects demi-cercle) ; voir Aspects pour le tableau des presets.

from ketu.aspects import calculate_aspects, CLASSICAL, TRADITIONAL, EXTENDED

# v1.1 default at the time (EXTENDED — all 14 aspects; the current v1.3+ default is TRADITIONAL)
all_aspects = calculate_aspects(jd)

# New v1.1: filter to classical only
classical = calculate_aspects(jd, aspects=CLASSICAL)

Nouveau : Systèmes de Maisons

ketu.houses est un nouveau sous-paquet — aucun code existant n’est cassé.

from ketu.houses import calculate_houses, house_of, SYSTEMS

h = calculate_houses(jd, lat=48.8566, lon=2.3522, system="placidus")
print(f"ASC: {h['asc']:.2f}°")

# Determine which house a planet is in
from ketu.calculations import long
sun_house = house_of(long(jd, 0), h["cusps"])

Corrections de Chemins d’Import (si mise à niveau depuis pre-1.0)

Si vous utilisiez l’ancien style import ketu; ketu.long(...) (qui n’a jamais été officiellement supporté comme API publique), passez aux imports de sous-modules corrects :

# Old (never worked correctly — ketu.long is not in ketu.__all__)
import ketu
lon = ketu.long(jd, 0)

# Correct (v1.0+)
from ketu.calculations import long
lon = long(jd, 0)

Mise à niveau de v0.4.0 vers v1.0.0

Suppression : Modules d’Export

Ketu 1.0 est une bibliothèque de calcul pure. Les fonctionnalités de visualisation et d’export de calendrier ont été supprimées :

Modules supprimés : ketu.export.chart, ketu.export.icalendar
Fonctions supprimées : draw_zodiacal_chart(), export_lunations_to_ical(), export_aspects_to_ical(), export_transits_to_ical()

Migration : Implémentez la visualisation dans votre couche applicative en utilisant les résultats de calcul de Ketu.

Suppression : Dépendance Pandas

generate_aspect_timeline() retourne maintenant un tableau structuré NumPy (était DataFrame)
AspectTimeline.to_pandas() supprimée
Migration : Utilisez import pandas as pd; df = pd.DataFrame(timeline) pour une conversion manuelle

Renommage : Fonctions de Vélocité (Incompatible)

vlong() → long_velocity()
vlat() → lat_velocity()
vdist_au() → dist_velocity_au()

Migration : Utilisez rechercher-remplacer dans votre code :

sed -i 's/ketu\.vlong(/ketu.long_velocity(/g' *.py
sed -i 's/ketu\.vlat(/ketu.lat_velocity(/g' *.py
sed -i 's/ketu\.vdist_au(/ketu.dist_velocity_au(/g' *.py

Modification : Surface de l’API Publique

ketu.__init__.py exporte uniquement les métadonnées + constantes de base
Fonctions accessibles via des imports de sous-modules : from ketu.calculations import long
ketu.__all__ liste explicitement l’API publique

Migration : La plupart des utilisateurs ne remarqueront pas ce changement. Si vous importiez depuis des modules internes, passez aux imports de l’API publique.

Corrections d’Exactitude (v0.4.0 → v1.0.0)

IMPORTANT : Ces corrections modifient les résultats de calcul. Recalculez les résultats mis en cache de la version 0.4.0.

Bug de précédence d’opérateur du cache : use_cache=False était ignoré en raison de parenthèses manquantes
Non-déterminisme de la vectorisation des aspects : calculate_aspects_vectorized() retourne maintenant des résultats cohérents
Enroulement de la vélocité lunaire : Vélocité correcte à la frontière 360°/0° (affichait auparavant des pics de ±360°)

Étapes de Migration (v0.4.0 → v1.0.0)

Étape 1 : Mettre à Jour le Paquet

pip install --upgrade ketu

Étape 2 : Mettre à Jour Votre Code

Remplacez les appels aux fonctions de vélocité :

# Before (v0.4.0)
v = ketu.vlong(jday, body_id)

# After (v1.0.0)
from ketu.calculations import long_velocity
v = long_velocity(jday, body_id)

Remplacez les conversions pandas :

# Before (v0.4.0)
timeline = ketu.generate_aspect_timeline(...)
df = timeline.to_pandas()

# After (v1.0.0)
import pandas as pd
timeline = ketu.generate_aspect_timeline(...)
df = pd.DataFrame(timeline)

Supprimez les appels chart/icalendar :

# Before (v0.4.0) - REMOVED
ketu.draw_zodiacal_chart(jday, output_file="chart.svg")
ketu.export_lunations_to_ical(start, end, "lunations.ics")

# After (v1.0.0) - No replacement
# Implement visualization in your application layer using ketu calculation results

Étape 3 : Tester Votre Code

Exécutez votre suite de tests pour détecter tout problème restant.

Étape 4 : Recalculer les Résultats Mis en Cache

Si vous avez mis en cache des résultats de calcul de la version 0.4.0, recalculez-les pour assurer leur justesse.

Retour Arrière

Les versions 0.3.0 et 0.4.0 n’ont pas été publiées sur PyPI, donc pip install ketu==0.4.0 ne fonctionnera pas. Si vous avez besoin du comportement précédent, installez depuis les sources :

git clone https://github.com/alkimya/ketu.git
cd ketu
git checkout v0.2.1  # Last published pre-NumPy version
pip install .

Note : v1.0.0 est la première version basée sur NumPy publiée sur PyPI. La version PyPI précédente est v0.2.1 (basée sur pyswisseph).

Obtenir de l’Aide

Si vous rencontrez des problèmes :

Consultez le Changelog pour la liste complète des changements
Ouvrez une issue