Settings (kerykeion.settings) #

This module handles the global configuration for Kerykeion calculations, default parameters, and cache management.

Configuration Constants #

Import from: kerykeion.settings.config_constants

Active Points Presets #

from kerykeion.settings.config_constants import (
    DEFAULT_ACTIVE_POINTS,
    TRADITIONAL_ASTROLOGY_ACTIVE_POINTS,
    ALL_ACTIVE_POINTS,
)

# Use extended point set
subject = AstrologicalSubjectFactory.from_birth_data(
    "Alice", 1990, 6, 15, 12, 0,
    lng=-0.1276, lat=51.5074, tz_str="Europe/London", online=False,
    active_points=ALL_ACTIVE_POINTS
)

# Use classical planets only (traditional/Hellenistic astrology)
subject = AstrologicalSubjectFactory.from_birth_data(
    "Alice", 1990, 6, 15, 12, 0,
    lng=-0.1276, lat=51.5074, tz_str="Europe/London", online=False,
    active_points=TRADITIONAL_ASTROLOGY_ACTIVE_POINTS
)

Active Aspects Presets #

DEFAULT_NATAL_POINT_ORB_ADJUSTMENTS ({"Sun": 1.5, "Moon": 1.5}) widens the orb for the luminaries in natal work; see Aspects for how the adjustments are combined.

from kerykeion import AspectsFactory
from kerykeion.settings.config_constants import ALL_ACTIVE_ASPECTS

aspects = AspectsFactory.single_chart_aspects(
    subject,
    active_aspects=ALL_ACTIVE_ASPECTS
)

Chart Configuration Presets #

Import from: kerykeion.settings.chart_defaults (also re-exported from kerykeion.settings)

Two builders extend the celestial-point settings at render time with entries the static table cannot hold, because the names are only known once the chart is computed:

Fixed-Star and Zodiac Defaults #

Import from: kerykeion.settings.config_constants

Settings Model #

KerykeionSettingsModel #

The settings are defined by a Pydantic model that controls the library’s language/localization behavior.

Key Configuration Options:

• language_settings: A dictionary mapping language codes (e.g., "EN", "IT") to KerykeionLanguageModel instances containing localized strings for planet names, signs, houses, etc.

(See kerykeion.schemas.settings_models for the full model definition)

Translation Utilities #

Import from: kerykeion.settings

Helper functions to access the library’s internal localization strings (planets, signs, etc.).

get_translations #

Fetches a localized string from the internal dictionary.

from kerykeion.settings import get_translations

# Get Italian name for Sun
sun_it = get_translations(
    "celestial_points.Sun",
    default="Sole",
    language="IT"
)
print(sun_it) # "Sole"

load_language_settings #

Returns the entire language setting dictionary, optionally merging with overrides.

from kerykeion.settings import load_language_settings

# Create custom overrides
overrides = {
    "IT": {
        "celestial_points": {"Sun": "Il Sole"}
    }
}
settings = load_language_settings(overrides)

load_language_pair #

load_language_pair(language, overrides=None) -> tuple[dict, dict]

Returns (selected_language, english_fallback) and materializes only those two, avoiding the full-table deepcopy load_language_settings performs. This is what ChartDrawer uses to resolve its labels.

from kerykeion.settings import load_language_pair

italian, english = load_language_pair("IT")
print(italian["celestial_points"]["Sun"])

load_settings_mapping (deprecated) #

Deprecated since 6.0.0, removed in 7.0.0. Use load_language_settings instead — it returns the same language mapping and accepts the same overrides. load_settings_mapping is no longer part of kerykeion.settings.__all__ and emits a DeprecationWarning when called.

Resolves the full configuration mapping, including overrides for bundled language settings.

# Preferred:
from kerykeion.settings import load_language_settings

settings = load_language_settings()

Advanced Settings Types #

These types are used internally for type hinting but are exported for advanced usage.

LANGUAGE_SETTINGS #

The raw dictionary containing all built-in translations. Modifying this directly is not recommended; use load_language_settings with overrides instead.

SettingsSource #

Type alias for Optional[Mapping[str, Any]]. Represents the structure of a settings override dictionary.

---