Vedākṣha

Integration Guide — Python Bindings

Native speed. Python ergonomics.

The vedaksha Python package exposes the full Rust computation engine via PyO3. You get native Rust performance, Python ergonomics, and full type stubs for IDE autocompletion and runtime validation.

The wheel ships with the DE440s embedded ephemeris for dates 1550–2650 CE. Extended coverage (DE441) requires loading an external file.

Installation

pipterminal
pip install vedaksha
uvterminal
uv add vedaksha
poetryterminal
poetry add vedaksha

Code Example

chart.py
import vedaksha as vk
from vedaksha import (
    ChartConfig, HouseSystem, Ayanamsha, DashaSystem,
    DataClass, Locale
)

# 1. Convert calendar date to Julian Day
jd = vk.calendar_to_jd(1990, 6, 15, hour_ut=10.5)
print(f"Julian Day: {jd}")    # → 2448057.9375

# 2. Compute a full natal chart
config = ChartConfig(
    house_system = HouseSystem.PLACIDUS,
    ayanamsha    = Ayanamsha.LAHIRI,
    data_class   = DataClass.ANONYMOUS,
)
chart = vk.compute_chart(jd, latitude=28.6139, longitude=77.2090, config=config)

# 3. Inspect planets
for planet in chart.planets:
    name = vk.planet_name(planet.body, locale=Locale.EN)
    sign = vk.sign_name(planet.sign, locale=Locale.EN)
    print(f"{name:8s}  {planet.longitude:8.3f}°  {sign:12s}  H{planet.house}")

# → Sun       336.142°  Pisces        H12
# → Moon       45.231°  Taurus        H1
# ...

# 4. Dashas — no ephemeris file needed for this
moon_longitude = chart.planets["Moon"].longitude
dasha = vk.compute_dasha(jd, moon_longitude=moon_longitude)
print(f"Mahadasha: {dasha.current.lord}, ends {dasha.current.end_date}")

# 5. Nakshatras — instant
nk = vk.get_nakshatra(moon_longitude)
print(f"Moon nakshatra: {nk.name} Pada {nk.pada}")  # → Rohini Pada 2

# 6. Emit to Cypher for Neo4j
cypher_statements = chart.graph.emit_cypher()
for stmt in cypher_statements:
    print(stmt)  # MERGE (c:Chart {id: ...}) ...

Available Functions

compute_chart(julian_day: float, latitude: float, longitude: float, config: ChartConfig | None = None) -> ChartGraph
stable

Compute a full natal chart. Returns a ChartGraph dataclass with .planets, .houses, .yogas, .aspects, and .graph. Requires ephemeris data loaded via load_ephemeris().

compute_dasha(julian_day: float, moon_longitude: float, system: DashaSystem = DashaSystem.VIMSHOTTARI) -> DashaTree
stable

Compute the dasha tree from a Moon longitude. Returns a recursive DashaTree with up to 5 levels of sub-periods. No ephemeris file needed.

get_nakshatra(longitude: float) -> Nakshatra
stable

Return the nakshatra and pada for any ecliptic longitude. Instant geometric calculation. No ephemeris needed.

compute_varga(chart: ChartGraph, division: int) -> ChartGraph
stable

Compute a divisional chart (D-1 through D-60) from an existing ChartGraph. Returns a new ChartGraph with independently computed positions.

compute_houses(sidereal_time: float, latitude: float, system: HouseSystem = HouseSystem.PLACIDUS) -> HouseCusps
stable

Compute house cusps from local sidereal time and latitude. Supports all 10 house systems including Placidus, Koch, Whole Sign, Equal, and Sripathi.

find_aspects(positions: list[BodyPosition], orbs: OrbConfig | None = None) -> list[Aspect]
stable

Detect aspects among a list of body positions you supply. Returns typed Aspect objects with orb, applying/separating flag, and strength score.

calendar_to_jd(year: int, month: int, day: int, hour_ut: float = 0.0) -> float
stable

Convert a proleptic Gregorian calendar date and UT hour to a Julian Day number. Zero dependencies.

compute_ayanamsha(julian_day: float, system: Ayanamsha = Ayanamsha.LAHIRI) -> float
stable

Return the ayanamsha value in decimal degrees for any of the 44 supported systems at any Julian Day.

planet_name(planet: Planet, locale: Locale = Locale.EN) -> str
stable

Return the localized name of a planet. Supports English, Hindi, Sanskrit, Tamil, Telugu, Kannada, and Bengali.

sign_name(sign: Sign, locale: Locale = Locale.EN) -> str
stable

Return the localized name of a zodiac sign in any of the 7 supported languages.

Type Stubs and IDE Support

The package ships with .pyi stub files for every public function and dataclass. This gives you full autocompletion, inline parameter hints, and type checking in any IDE or type checker that supports PEP 484.

vedaksha/__init__.pyi (excerpt)
from dataclasses import dataclass
from enum import Enum
from typing import Optional

class HouseSystem(Enum):
    PLACIDUS = "Placidus"
    WHOLE_SIGN = "WholeSign"
    EQUAL = "Equal"
    KOCH = "Koch"
    CAMPANUS = "Campanus"
    REGIOMONTANUS = "Regiomontanus"
    SRIPATHI = "Sripathi"
    # ... 3 more

class Ayanamsha(Enum):
    LAHIRI = "Lahiri"
    FAGAN_BRADLEY = "FaganBradley"
    KRISHNAMURTI = "Krishnamurti"
    # ... 41 more

@dataclass
class Planet:
    body:       "PlanetBody"
    longitude:  float           # ecliptic, 0–360
    latitude:   float
    distance:   float           # AU
    speed:      float           # degrees/day
    retrograde: bool
    sign:       "Sign"
    house:      int             # 1–12
    nakshatra:  "Nakshatra"
    dignity:    "Dignity"

def compute_chart(
    julian_day: float,
    latitude:   float,
    longitude:  float,
    config:     Optional["ChartConfig"] = None,
) -> "ChartGraph": ...

def calendar_to_jd(
    year:    int,
    month:   int,
    day:     int,
    hour_ut: float = 0.0,
) -> float: ...

Localized Names

Every astronomical name can be rendered in 7 languages. Pass a Locale value to planet_name(), sign_name(), and nakshatra_name().

Locale.ENLocale.HILocale.SALocale.TALocale.TELocale.KNLocale.BN