Occultation Factory #

The OccultationFactory searches for lunar occultations – events where the Moon passes in front of a planet or star as seen from Earth. It wraps the ephemeris backend’s occultation functions (libephemeris by default) for both global and location-specific searches.

Basic Usage #

from kerykeion import OccultationFactory
from kerykeion.ephemeris_backend import ephe

factory = OccultationFactory()

# Find next 3 global occultations of Venus
jd_start = ephe.julday(2025, 1, 1, 0.0)
events = factory.search_global(jd_start, ephe.VENUS, count=3)

for occ in events:
    print(f"{occ.planet_name}: {occ.type} on {occ.datestamp}")

Methods #

search_global(julian_day, planet_id, count) #

Find occultations visible from anywhere on Earth.

Returns: List[OccultationModel]

search_local(julian_day, planet_id, lat, lng, count) #

Find occultations visible from a specific location.

Returns: List[OccultationModel]

For both search methods, count must be between 0 and 1,000 inclusive; invalid counts raise ValueError before any backend call. A planet_id that is neither an int nor a str raises TypeError, and a body outside the occultable set (see Planet Identifiers) raises KerykeionException.

# Find occultations visible from Rome
events = factory.search_local(
    julian_day=ephe.julday(2025, 1, 1, 0.0),
    planet_id=ephe.SATURN,
    lat=41.9028,
    lng=12.4964,
    count=5,
)

Planet Identifiers #

planet_id accepts either an ephe constant or the body’s name as a string:

A name is resolved through the project-wide name-to-ID map, so factory.search_global(jd, "Venus") and factory.search_global(jd, ephe.VENUS) are equivalent.

Accepted Bodies #

Only physically real bodies can be occulted by the Moon, so both forms are restricted to: Sun, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, Pholus, Ceres, Pallas, Juno, Vesta.

Anything else raises:

• KerykeionException — an unknown planet name, or a known name/ID outside the set above: the calculated points (lunar nodes, Lilith and apogee variants, the Uranian hypotheticals) have no disk to be covered, and the Moon and the Earth are not occultable either.
• TypeError — a planet_id that is neither an int nor a str (booleans included).

Data Models #

OccultationModel #

---