Settings¶

This reference documents how Monkay loads, caches, overrides, and evaluates settings objects.

Settings Sources¶

Monkay.settings can be configured from:

a dotted path ("module:attribute"),
a settings class,
a callable returning a settings source,
an already-instantiated settings object.

When settings resolve to a class/path, Monkay caches the parsed object. Callable sources can be used for dynamic forwarding patterns.

Evaluate Settings¶

evaluate_settings(...) processes optional preload and extension lists from the current settings object.

Parameters¶

on_conflict: extension conflict policy ("error", "keep", "replace")
ignore_import_errors: return False instead of raising on settings import/unset errors
ignore_preload_import_errors: continue when preload imports fail
onetime: skip re-evaluation when settings already evaluated in current context

Example¶

monkay.evaluate_settings(on_conflict="replace", onetime=False)

Forwarding Settings¶

Forwarding allows a package to delegate settings to another package.

Child package¶

import os

from monkay import Monkay

monkay = Monkay(
    globals(),
    settings_path=lambda: os.environ.get("MONKAY_CHILD_SETTINGS", "foo.test:example") or "",
)

Main package¶

import os

import child

from monkay import Monkay

monkay = Monkay(
    globals(),
    settings_path=lambda: os.environ.get("MONKAY_MAIN_SETTINGS", "foo.test:example") or "",
)
# because monkay.settings is an instance it uses not a cache for the settings
child.monkay.settings = lambda: monkay.settings

Lazy Settings Setup¶

import os
from dataclasses import dataclass

from monkay import Monkay


@dataclass
class Settings:
    env: str


@dataclass
class ProductionSettings(Settings):
    env: str = "production"


@dataclass
class DebugSettings(Settings):
    env: str = "debug"


def lazy_loader():
    # Lazy setup based on environment variables
    if not os.environ.get("DEBUG"):
        return os.environ.get("MONKAY_MAIN_SETTINGS", "foo.test:example") or ""
    elif os.environ.get("PERFORMANCE"):
        # must be class to be cached
        return ProductionSettings
    else:
        # not a class, will evaluated always on access
        return DebugSettings()


monkay = Monkay(
    globals(),
    # Required for initializing settings feature
    settings_path=lazy_loader,
)

# Now the settings are applied
monkay.evaluate_settings()

Multi-Stage Resolution¶

from monkay import Monkay

monkay = Monkay(
    globals(),
    # Required for initializing settings feature
    settings_path="",
)


def find_settings():
    for path in ["a.settings", "b.settings.develop"]:
        monkay.settings = path
        if monkay.evaluate_settings(ignore_import_errors=True):
            break

Temporary Settings Overrides¶

Use with_settings(...) for context-local overrides:

with monkay.with_settings(custom_settings):
    monkay.evaluate_settings(onetime=False)

Use with_settings(None) to temporarily disable override and access the base settings definition.

Clearing Settings Cache¶

monkay.clear_caches(settings_cache=True, import_cache=False)

Settings Preloads and Extensions¶

settings_preloads_name points to a list of preload strings
settings_extensions_name points to extension objects/factories/classes

These are only evaluated when evaluate_settings(...) is called.

Error Behavior¶

Disabled/unset settings access raises UnsetError.
Unknown on_conflict values raise ValueError.
Import failures raise ImportError unless suppressed with ignore_import_errors=True.