Astrological Subject Factory #

The AstrologicalSubjectFactory is the central mechanism in Kerykeion for creating AstrologicalSubject instances. It handles the complex astronomical calculations required to generate a chart, supporting widely used zodiacs, house systems, and coordinate perspectives.

Key Features #

• Precision: Uses the Swiss Ephemeris (via pyswisseph) for high-accuracy calculations.
• Flexibility: Supports Tropical/Sidereal zodiacs, multiple House systems (Placidus, Whole Sign, etc.), and various coordinate (Geocentric/Heliocentric) perspectives.
• Optimization: The active_points argument allows you to calculate only what you need, saving resources.
• Online/Offline: Can resolve locations automatically via GeoNames (Online) or accept raw coordinates (Offline).

Factory Methods #

1. from_birth_data (Primary) #

Creates a subject from standard civil birth details.

from kerykeion import AstrologicalSubjectFactory

# Online mode (requires GeoNames username)
subject = AstrologicalSubjectFactory.from_birth_data(
    name="John Doe",
    year=1990, month=6, day=15,
    hour=14, minute=30,
    city="London", nation="GB",
    geonames_username="your_username",
    zodiac_type="Tropical",
    houses_system_identifier="P"  # Placidus
)

print(f"Sun: {subject.sun.sign} {subject.sun.abs_pos:.2f}°")
print(f"Ascendant: {subject.ascendant.sign} {subject.ascendant.abs_pos:.2f}°")

Parameters:

2. from_iso_utc_time #

Creates a subject from a UTC ISO 8601 timestamp, useful for event charts or standardized data.

subject = AstrologicalSubjectFactory.from_iso_utc_time(
    name="Event Chart",
    iso_utc_time="2023-06-21T12:00:00Z",
    city="New York", nation="US",
    geonames_username="your_username"
)

Parameters:

Creates a subject for the current moment (“Now”), useful for Horary astrology or transits. Uses the system clock – does not accept year/month/day/hour/minute parameters.

now_chart = AstrologicalSubjectFactory.from_current_time(
    name="Current Transits",
    city="Tokyo", nation="JP",
    geonames_username="your_username"
)

Parameters:

Understanding Position Fields #

Every KerykeionPointModel (planet, angle, etc.) has two position fields:

Use position for display purposes and abs_pos for calculations (aspect detection, midpoints, etc.).

Configuration Options #

House Systems (houses_system_identifier) #

Zodiac Types #

• Tropical (Default): Fixed to seasons (0° Aries = Vernal Equinox). Standard in Western astrology.
• Sidereal: Fixed to constellations. Standard in Vedic astrology. Requires sidereal_mode.
  • 48 modes total: 47 named + USER for custom ayanamsa definitions.
  • Common Modes: LAHIRI (most common), FAGAN_BRADLEY, RAMAN.
  • USER mode: Requires custom_ayanamsa_t0 (Julian Day epoch) and custom_ayanamsa_ayan_t0 (degrees at epoch).
  • The computed ayanamsa offset is available via subject.ayanamsa_value (degrees, None for tropical).

Perspectives #

• Apparent Geocentric (Default): Earth-centered, includes light-time correction.
• True Geocentric: Earth-centered, geometric position only.
• Heliocentric: Sun-centered. Earth becomes a planet.
• Topocentric: Observer-centered (surface of Earth), accounts for parallax.

Performance & Optimization #

Subject creation involves complex calculations. For high-performance applications (e.g., scanning thousands of dates), limit the active_points to only what you need.

# Minimal calculation (approx. 3-4x faster than full)
fast_chart = AstrologicalSubjectFactory.from_birth_data(
    name="Research Point",
    year=2000, month=1, day=1,
    hour=12, minute=0,
    city="London", nation="GB",
    geonames_username="your_username",
    # Only calculate luminaries and angles
    active_points=["Sun", "Moon", "Ascendant", "Medium_Coeli"]
)

Internal Types #

These @dataclass structures are used internally but are exposed for reference.

ChartConfiguration #

Dataclass holding chart calculation settings. Fields: zodiac_type, sidereal_mode, houses_system_identifier, perspective_type, custom_ayanamsa_t0, custom_ayanamsa_ayan_t0.

LocationData #

Dataclass carrying raw location information. Fields: city, nation, lng, lat, tz_str, altitude, city_data.

ephemeris_context #

Helper context manager for thread-safe Swisseph calculations. Not intended for public use.

Memory Usage:

• Full Chart: ~50KB
• Minimal Chart: ~15KB

Thread Safety Note #

The underlying Swiss Ephemeris library is not thread-safe by default. If using Kerykeion in a multi-threaded web server (like Gunicorn/Uvicorn workers), ensure AstrologicalSubjectFactory usage is process-isolated or appropriately locked if sharing state (though Kerykeion objects themselves are generally self-contained).

---

Need this in production? Use the Astrologer API for hosted calculations, charts, and AI interpretations - no server setup required. Learn more →