Configuration¶

Flexible configuration management with multi-format support, cascading search, and type-checked access.

TL;DR¶

from kstlib.config import ConfigLoader

# Load with auto-discovery (recommended)
config = ConfigLoader().config

# Access with dot notation
print(config.app.name)
print(config.database.host)

# Export default config to customize
kstlib config export --out kstlib.conf.yml

Key Features¶

Multi-format support: YAML, TOML, JSON, and INI
Cascading search: Automatic discovery across multiple locations
Include system: Compose configs from multiple files
Deep merge: Intelligent merging of nested configurations
Dot notation: Easy access to nested values via Box
Type safety: Full type hints for IDE support

Quick Start¶

# kstlib.conf.yml
app:
  name: "My Application"
  debug: true

database:
  host: "localhost"
  port: 5432

from kstlib.config import load_from_file

# 1. Load from specific file
config = load_from_file("kstlib.conf.yml")

# 2. Or use auto-discovery
from kstlib.config import ConfigLoader
config = ConfigLoader().config

# 3. Access values with dot notation
print(config.app.name)       # "My Application"
print(config.database.port)  # 5432

How It Works¶

Loading Strategies¶

Cascading mode (recommended) searches multiple locations in order:

config = ConfigLoader().config

Search order (priority from highest to lowest):

Current working directory (./kstlib.conf.yml)
User’s home directory (~/kstlib.conf.yml)
User’s config directory (~/.config/kstlib.conf.yml)
System-wide config dirs via platformdirs.site_config_dir:
- Linux: /etc/xdg/kstlib/ plus every entry in $XDG_CONFIG_DIRS
- macOS: /Library/Application Support/kstlib/
- Windows: %PROGRAMDATA%/kstlib/
Package defaults (lowest priority)

System-wide entries are merged silently. If a file does not exist at a given location, it is skipped without warning or error. This lets operators drop a shared kstlib.conf.yml in /etc/xdg/kstlib/ (or the platform equivalent) while users override individual keys in their home directory.

See System-Wide Configuration below for the full per-OS defaults and the rules that apply when XDG_CONFIG_DIRS lists several directories.

Direct mode loads from a specific file:

config = load_from_file("path/to/config.yml")

Environment variable mode loads from a path in an env var:

# Uses CONFIG_PATH env var by default
config = ConfigLoader(auto_source="env").config

# Or specify a different env var name
config = ConfigLoader(auto_source="env", auto_env_var="MYAPP_CONFIG_FILE").config

System-Wide Configuration¶

System-wide configuration lets operators ship shared defaults (corporate endpoints, logging targets, TLS settings, audit rules, …) from a location that every user of a machine inherits automatically. Users keep their own ~/.config/kstlib.conf.yml and the cascade merges the two without any manual wiring.

Under the hood, kstlib delegates path discovery to platformdirs.site_config_dir, so the behavior matches every other well-behaved XDG-aware tool.

Default paths per OS¶

Platform	Default system config path
Linux / BSD	`/etc/xdg/kstlib/kstlib.conf.yml`
macOS	`/Library/Application Support/kstlib/kstlib.conf.yml`
Windows	`%PROGRAMDATA%\kstlib\kstlib.conf.yml` (typically `C:\ProgramData\kstlib\kstlib.conf.yml`)

Note

On Windows and macOS, writing to these paths usually requires administrator or root privileges. That is intentional: system-wide config is meant to be provisioned by an operator or a configuration management tool (Ansible, Puppet, Chef, Intune, …), not hand-edited by end users.

Linux: `XDG_CONFIG_DIRS` semantics¶

On Linux and other XDG-compliant Unices, kstlib honors the standard XDG Base Directory Specification. The XDG_CONFIG_DIRS environment variable takes a colon-separated list of directories, ordered from highest to lowest priority:

# /etc/corp/kstlib wins over /etc/xdg/kstlib for common keys
export XDG_CONFIG_DIRS=/etc/corp:/etc/xdg

If XDG_CONFIG_DIRS is unset, kstlib falls back to the single default /etc/xdg/kstlib/.

Each directory in the list is probed for kstlib.conf.yml. kstlib then deep-merges every file it finds, so keys defined in the higher-priority directory override identical keys in the lower-priority ones, while non-conflicting keys are unioned.

Tip

You can inspect what kstlib will probe on your machine:

python -c "import platformdirs; print(platformdirs.site_config_dir('kstlib', appauthor=False, multipath=True))"

Full cascade at a glance¶

From lowest to highest priority (later entries override earlier ones):

1. Package defaults (shipped inside kstlib)
2. System config dirs:
     - $XDG_CONFIG_DIRS entries (Linux, if set)      <- lowest system priority
     - /etc/xdg/kstlib (Linux default, if XDG unset)
     - /Library/Application Support/kstlib (macOS)
     - %PROGRAMDATA%\kstlib (Windows)                <- highest system priority
3. ~/.config/kstlib.conf.yml
4. ~/kstlib.conf.yml
5. ./kstlib.conf.yml (cwd)                           <- highest overall
6. Runtime kwargs (supersede every file source)

Missing files at any level are skipped silently. This is the whole point: deployments can pre-provision a system file, and machines that do not have one simply fall through to the next layer.

Example: corporate baseline + user overrides¶

# /etc/xdg/kstlib/kstlib.conf.yml (shipped by IT)
logger:
  defaults:
    output: file
    rotation: daily
alerts:
  channels:
    slack:
      webhook_url: https://hooks.slack.com/services/OPS/CORP/XXXXX

# ~/.config/kstlib.conf.yml (written by the developer)
logger:
  defaults:
    level: DEBUG  # Adds to the corporate baseline

The effective configuration for this user is:

logger:
  defaults:
    output: file       # from system
    rotation: daily    # from system
    level: DEBUG       # from user (added)
alerts:
  channels:
    slack:
      webhook_url: https://hooks.slack.com/services/OPS/CORP/XXXXX  # from system

The developer cannot accidentally lose the corporate Slack webhook or the file-rotation policy, but they can still opt into DEBUG locally.

Opting out¶

System-wide config is always active in cascading mode, but you can bypass it entirely by using direct mode:

from kstlib.config import load_from_file

# Only this file is loaded - no cascade, no system dirs
config = load_from_file("/opt/myapp/isolated.yml")

Or by scoping the loader to an explicit file:

from kstlib.config import ConfigLoader

loader = ConfigLoader(auto_source="file", auto_path="./test.yml")

Include System¶

Compose configurations from multiple files:

# main.yml
include:
  - database.toml
  - features.json

app:
  name: "My App"

Deep merge behavior:

Nested dictionaries are recursively merged
Lists are replaced (not merged)
Later values override earlier ones

Warning

Override priority matters! Values are merged left-to-right with later sources overwriting earlier ones:

package defaults → user config file → includes → kwargs

This means a value in your config file will override package defaults, and kwargs passed at runtime will override everything else.

Example: If package defaults set app.debug: false and your config file has app.debug: true, the final value is true. If you then pass debug=False as a kwarg, it becomes False again.

Supported Formats¶

Format	Extensions	Notes
YAML	`.yml`, `.yaml`	Recommended, supports comments
TOML	`.toml`	Good for hierarchical data
JSON	`.json`	Strict, no comments
INI	`.ini`	Legacy support

Caching¶

Config is cached after first load:

from kstlib.config import get_config, clear_config

config = get_config()        # Cached config (fast)
config = get_config(max_age=0)  # Force reload
clear_config()               # Clear cache entirely

Interactive usage (Jupyter / REPL)¶

The config singleton is intentionally cached: services that run for hours should not re-read the YAML files on every access. In interactive sessions though, you often edit the config and want the change to take effect immediately, without restarting the kernel.

Warning

If you edit a kstlib.conf.yml file (for example /etc/xdg/kstlib/kstlib.conf.yml, ~/.config/kstlib.conf.yml, or the one in your current working directory) while a Python session is running, call reload_config() to force a refresh. Without this, the singleton cache keeps the old values and get_config() will continue to return the stale Box.

reload_config() is the explicit, discoverable alias for “flush the cache and re-read from disk”. It is equivalent to clear_config() followed by get_config(), but expresses the intent in a single call.

from kstlib.config import reload_config

# ... you just edited ~/.config/kstlib.conf.yml in another window ...
cfg = reload_config()
print(cfg.mail.default)  # reflects the edit

It is also available at the top level, consistent with get_config and clear_config:

import kstlib

cfg = kstlib.reload_config()

When to use which:

Call	Purpose
`reload_config()`	One-shot refresh in interactive work. Clearest intent.
`get_config(force_reload=True)`	Same behaviour, but the intent is hidden in a kwarg.
`clear_config()`	Only flushes the cache. The next `get_config()` call reloads. Useful in tests that want to isolate the cache boundary explicitly.

Note

Known issue fixed in 2.3.1: on kstlib 2.3.0, importing kstlib.mail as the very first kstlib symbol in a fresh Python process (for example right after Restart Kernel in Jupyter) could raise ImportError due to a circular import between kstlib.limits and kstlib.config.loader. Affected versions: 2.3.0 only. Workaround for users still on 2.3.0: import kstlib.config before the first from kstlib.mail import .... Upgrading to 2.3.1 or later removes the need for the workaround.

Configuration¶

CLI Export¶

Bootstrap configuration files from package defaults:

# Export full default config
kstlib config export --out kstlib.conf.yml

# Export specific section
kstlib config export --section secrets --out secrets.yml

# Preview to stdout
kstlib config export --stdout

Environment-Based Structure¶

Recommended project layout:

myapp/
├── config/
│   ├── base.yml          # Defaults (committed)
│   ├── development.yml   # Dev overrides
│   ├── production.yml    # Prod overrides
│   └── secrets.yml       # Local secrets (gitignored)
└── src/

# config/base.yml
app:
  name: "My Application"
  debug: false
  log_level: INFO

database:
  pool_size: 10
  timeout: 30

# config/development.yml
include: base.yml

app:
  debug: true
  log_level: DEBUG

database:
  host: localhost

Strict Format Mode¶

Enforce format consistency (all includes must match parent format):

config = load_from_file("config.yml", strict_format=True)

Default Configuration¶

The package ships with sensible defaults. Export to customize:

kstlib config export --out kstlib.conf.yml

Note

Partial override only: You do not need to copy the entire default configuration. The system deep-merges your config with package defaults, so you only specify what you want to change:

# Minimal user config - only override what you need
logger:
  defaults:
    output: file  # Everything else uses package defaults

cache:
  default_strategy: lru

This keeps your config clean and maintainable. For larger projects, you can also split your config into multiple files using the include: directive.

View default configuration

# Default configuration for kstlib
# This file is used to set default values for the kstlib library.

###########################################################################################
## Internal kstlib behavior (opt-in switches controlling library-side features)
###########################################################################################
kstlib:
  # Internal logging activation
  # ---------------------------
  # Controls whether kstlib's own log records (from kstlib.auth, kstlib.mail,
  # kstlib.rapi, ...) are emitted when a consumer never calls init_logging()
  # explicitly. Disabled by default so applications embedding kstlib stay
  # silent unless they opt in.
  #
  # When enabled, the first call to get_logger() reads this section and
  # triggers init_logging(preset=...) transparently. Any error (missing
  # config file, parse failure, etc.) is swallowed silently so kstlib can
  # never break the host application through this cascade.
  logging:
    enabled: false   # Opt-in: set to true to activate internal kstlib logs
    preset: prod     # Preset used by auto-init: dev, prod, debug, trace, ...
                     # Unknown presets fall back to "prod" with a one-line
                     # stderr notice listing available names.

    # Per-logger level override (optional, default = no filtering).
    #
    # When set, each entry calls logging.getLogger(name).setLevel(level)
    # right after the kstlib root logger is registered. Useful to silence
    # the noise of a specific sub-package (e.g. RAPI config loader emitting
    # 1300+ DEBUG lines per startup) without dropping the level globally.
    #
    # Cascade (lowest to highest priority):
    #   1. kstlib.logging.modules               (this section, global default)
    #   2. logger.presets.<active>.modules      (preset-specific override)
    #   3. CLI flag --log-module                (repeatable, REPLACES YAML;
    #                                            three syntaxes, see below)
    # Steps 1 and 2 are merged key-by-key; preset wins on shared keys.
    #
    # Convention: every kstlib logger follows kstlib.<sub-package>[.<module>],
    # mirroring the layout of src/kstlib/. Examples:
    #   kstlib.rapi, kstlib.rapi.client, kstlib.rapi.config
    #   kstlib.transform, kstlib.transform.chain
    #
    # Available sub-packages:
    #   kstlib.alerts, kstlib.auth, kstlib.cache, kstlib.cli, kstlib.config,
    #   kstlib.db, kstlib.helpers, kstlib.logging, kstlib.mail, kstlib.metrics,
    #   kstlib.monitoring, kstlib.ops, kstlib.pipeline, kstlib.rapi,
    #   kstlib.resilience, kstlib.secrets, kstlib.secure, kstlib.ssl,
    #   kstlib.transform, kstlib.ui, kstlib.utils, kstlib.websocket
    #
    # For the full module list, browse src/kstlib/ or the Sphinx
    # "Logging introspection guide".
    #
    # Supported levels (see Sphinx "Logging introspection guide"):
    #   TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL
    # Names are case-insensitive. Invalid entries are skipped with a
    # WARNING (and WARNING [SECURITY] for names not starting with kstlib.).
    #
    # Defaults: kstlib.rapi.config and kstlib.config.loader are the
    # most verbose loggers at startup (1300+ DEBUG/TRACE lines for
    # rapi.config on a typical Viya install, large cascade trace for
    # config.loader when many includes are present). Both muted to
    # WARNING by default; raise them locally when you need to debug.
    #
    # Module mutes are PERSISTENT by design: -v/-vv/-vvv and --log-level
    # only adjust the root handler level. They do NOT reset these
    # mutes, so noisy modules stay quiet even under -vvv.
    #
    # Override surfaces (priority increasing):
    #   - user kstlib.conf.yml: modules: {kstlib.rapi.config: DEBUG}
    #     (deep merge with these defaults, override per-module)
    #   - preset-specific: presets.<name>.modules: {...}
    #   - CLI --log-module: per-invocation override, three syntaxes
    #     (1) classic, fully-qualified
    #         --log-module kstlib.rapi.config=TRACE
    #     (2) classic, prefix omitted (kstlib. auto-prepended)
    #         --log-module rapi.config=TRACE
    #     (3) inverse, level groups module list
    #         --log-module DEBUG=foo.bar,baz.qux
    modules:
      kstlib.rapi.config: WARNING
      kstlib.config.loader: WARNING

###########################################################################################
## Datetime formatting (global settings for timestamp display)
###########################################################################################
datetime:
  # Format string for timestamps (pendulum format tokens)
  # See: https://pendulum.eustace.io/docs/#tokens
  # Common formats:
  #   - "YYYY-MM-DD HH:mm:ss" (ISO-like, default)
  #   - "DD/MM/YYYY HH:mm:ss" (European)
  #   - "MM/DD/YYYY hh:mm:ss A" (US with AM/PM)
  #   - "ddd D MMM YYYY HH:mm" (Human: "Mon 29 Jan 2026 15:30")
  # Hard limit: max 64 chars, alphanumeric + common punctuation only
  format: "YYYY-MM-DD HH:mm:ss"

  # Timezone for display: "local" (system timezone) or IANA timezone name
  # Examples: "local", "UTC", "Europe/Paris", "America/New_York"
  # Hard limit: max 64 chars, validated against pendulum timezones
  timezone: "local"

###########################################################################################
## Cache configuration
###########################################################################################
cache:
  # Default caching strategy (ttl | lru | memoize | file)
  default_strategy: ttl

  # TTL (Time-To-Live) cache settings
  ttl:
    default_seconds: 300 # 5 minutes
    max_entries: 1000 # Maximum number of cached entries
    cleanup_interval: 60 # Cleanup expired entries every 60s

  # LRU (Least Recently Used) cache settings
  lru:
    maxsize: 128 # Maximum cache size
    typed: false # Separate cache for different argument types

  # File-based cache settings
  file:
    enabled: true
    cache_dir: ".cache" # Directory for cache files
    check_mtime: true # Invalidate cache on file modification
    serializer: json # json (default) | pickle | auto
    # Maximum cache file size (prevents OOM on corrupted files)
    # Accepts: bytes (int) or human-readable string ("100M", "50 MiB")
    # Hard limit enforced in code: 100 MiB
    max_file_size: "50M"

  # Async cache support
  async_support:
    enabled: true
    executor_workers: 4 # ThreadPoolExecutor workers for sync functions

  # Metrics and monitoring
  metrics:
    enabled: false # Track cache hits/misses (opt-in)
    log_stats: false # Log statistics periodically
    stats_interval: 300 # Log stats every 5 minutes

###########################################################################################
## Logging configuration
###########################################################################################
logger:
  defaults:
    output: console # console | file | both

    # Color theme for Rich console output
    theme:
      trace: "medium_purple4 on dark_olive_green1"
      debug: "black on deep_sky_blue1"
      info: "sky_blue1"
      success: "black on sea_green3"
      warning: "bold white on salmon1"
      error: "bold white on deep_pink2"
      critical: "blink bold white on red3"

    # Icons for each log level
    icons:
      show: true
      trace: "🔬"
      debug: "🔎"
      info: "📄"
      success: "✅"
      warning: "🚨"
      error: "❌"
      critical: "💀"

    # Console handler settings
    console:
      level: WARNING  # Log level: TRACE | DEBUG | INFO | SUCCESS | WARNING | ERROR | CRITICAL
      datefmt: "%Y-%m-%d %H:%M:%S"
      format: "::: PID %(process)d / TID %(thread)d ::: %(message)s"
      show_path: true
      tracebacks_show_locals: true

    # File handler settings
    # Two configuration styles are supported:
    #   - New style (recommended): file_path: ./logs/kstlib.log
    #   - Legacy style: log_path + log_dir + log_name (for backward compatibility)
    # The new style takes priority if file_path is defined.
    file:
      level: WARNING  # Log level: TRACE | DEBUG | INFO | SUCCESS | WARNING | ERROR | CRITICAL
      datefmt: "%Y-%m-%d %H:%M:%S"
      format: "[%(asctime)s | %(levelname)-8s] ::: PID %(process)d / TID %(thread)d ::: %(message)s"
      # file_path: ./logs/kstlib.log  # New style (recommended)
      # auto_create_dir: true          # New style auto-create
      log_path: "./"                   # Legacy style (kept for backward compatibility)
      log_dir: "logs"
      log_name: "kstlib.log"
      log_dir_auto_create: true

    # File rotation settings
    rotation:
      when: midnight # midnight | S | M | H | D | W0-W6
      interval: 1
      backup_count: 7

  presets:
    dev:
      output: console
      console:
        level: DEBUG
        show_path: true
        tracebacks_show_locals: true
      icons:
        show: true

    prod:
      output: file
      file:
        level: INFO
      icons:
        show: false

    # debug: deeper-than-dev preset for investigation sessions.
    # Persists to file (output: both) so logs survive the terminal and can be
    # grepped or shared after the fact, and emits at TRACE so HTTP traces and
    # detailed diagnostics are captured. Use 'dev' for everyday iteration
    # (console-only, DEBUG); use 'debug' when actively investigating an issue.
    debug:
      output: both
      console:
        level: TRACE
        show_path: true
        tracebacks_show_locals: true
      file:
        level: TRACE
        format: "[%(asctime)s | %(levelname)-8s] ::: PID %(process)d / TID %(thread)d ::: [%(filename)s:%(lineno)d %(funcName)s] %(message)s"
      icons:
        show: true

    trace:
      output: both
      console:
        level: TRACE
        show_path: true
        tracebacks_show_locals: true
      file:
        level: TRACE
        format: "[%(asctime)s | %(levelname)-8s] ::: PID %(process)d / TID %(thread)d ::: [%(filename)s:%(lineno)d %(funcName)s] %(message)s"
      icons:
        show: true

    # Mail trace preset - verbose SMTP/SSL debugging to dedicated file
    # Usage: LogManager(preset="trace_mail") or logger.preset: trace_mail
    trace_mail:
      output: both
      console:
        level: WARNING  # Keep console quiet
      file:
        level: TRACE
        file_path: ./logs/mail-trace.log
        auto_create_dir: true
      icons:
        show: true

###########################################################################################
## UI helpers configuration
###########################################################################################
ui:
  panels:
    defaults:
      panel:
        # border_style supports any Rich color/style (e.g. "blue", "bold green")
        border_style: "bright_blue"
        title_align: "left"
        subtitle_align: "left"
        padding: [1, 2]
        expand: true
        highlight: false
        # https://rich.readthedocs.io/en/stable/appendix/box.html#appendix-box
        box: "ROUNDED"
      content:
        box: "SIMPLE"
        expand: true
        show_header: false
        key_label: "Key"
        value_label: "Value"
        key_style: "bold white"
        value_style: null
        header_style: "bold"
        pad_edge: false
        sort_keys: false
        use_markup: true
        use_pretty: true
        pretty_indent: 2
    presets:
      info:
        panel:
          border_style: "cyan"
          title: "Information"
          icon: "📘"
      success:
        panel:
          border_style: "sea_green3"
          title: "Success"
          icon: "✅"
      warning:
        panel:
          border_style: "orange3"
          title: "Warning"
          icon: "🔔"
      error:
        panel:
          border_style: "red3"
          title: "Error"
          icon: "❌"
      summary:
        panel:
          border_style: "light_steel_blue1"
          title: "Execution Summary"
          icon: "📝"
        content:
          sort_keys: true
          key_style: "bold orchid2"
          value_style: "dim white"
  tables:
    defaults:
      table:
        title: null
        caption: null
        box: "SIMPLE"
        show_header: true
        header_style: "bold cyan"
        show_lines: false
        row_styles: null
        expand: true
        pad_edge: false
        highlight: false
      columns:
        - header: "Key"
          key: "key"
          justify: "left"
          style: "bold white"
          overflow: "fold"
          no_wrap: false
        - header: "Value"
          key: "value"
          justify: "left"
          style: null
          overflow: "fold"
          no_wrap: false
    presets:
      inventory:
        table:
          title: "Inventory"
          box: "SIMPLE_HEAVY"
          show_lines: true
          header_style: "bold yellow"
        columns:
          - header: "Component"
            key: "component"
            style: "bold"
            width: 18
          - header: "Version"
            key: "version"
            style: "cyan"
            width: 12
          - header: "Status"
            key: "status"
            justify: "center"
            style: "bold"
            width: 10
      metrics:
        table:
          title: "Metrics"
          box: "SIMPLE_HEAD"
          header_style: "bold green"
        columns:
          - header: "Metric"
            key: "metric"
            style: "bold"
          - header: "Value"
            key: "value"
            justify: "right"
  spinners:
    defaults:
      # Spinner character style: BRAILLE | DOTS | LINE | ARROW | BLOCKS | CIRCLE | SQUARE | MOON | CLOCK
      style: "BRAILLE"
      # Position relative to message: before | after
      position: "before"
      # Animation type: spin | bounce | color_wave
      animation_type: "spin"
      # Seconds between animation frames
      interval: 0.08
      # Rich style for spinner character
      spinner_style: "cyan"
      # Rich style for message text (null = default)
      text_style: null
      # Character shown on success
      done_character: "✓"
      done_style: "green"
      # Character shown on failure
      fail_character: "✗"
      fail_style: "red"
    presets:
      minimal:
        style: "LINE"
        spinner_style: "dim white"
        interval: 0.1
      fancy:
        style: "BRAILLE"
        spinner_style: "bold cyan"
        interval: 0.06
      blocks:
        style: "BLOCKS"
        spinner_style: "blue"
        interval: 0.05
      bounce:
        animation_type: "bounce"
        spinner_style: "yellow"
        interval: 0.08
      color_wave:
        animation_type: "color_wave"
        interval: 0.1

###########################################################################################
## Mail configuration
###########################################################################################
mail:
  # Default named preset used when MailBuilder() is instantiated without
  # transport= or preset=. Must match a key under mail.presets below.
  # Leave null to force callers to pass transport= or preset= explicitly.
  default: null

  # Anti-spam throttle (kill switch). Enforced before the transport on
  # every MailBuilder.send(), including indirect calls via @mail.notify.
  #
  # Cascade (highest priority first):
  #   1. mail.presets.<name>.throttle.<key>  (preset-level override)
  #   2. mail.throttle.<key>                 (this section, mail-wide default)
  #   3. Code defaults                       (rate=20, per=60.0, on_exceed=raise)
  #
  # Each key cascades independently: a preset can override only ``rate``
  # while keeping the mail-wide ``per`` and ``on_exceed``.
  #
  # Modes:
  #   - raise (default): emits WARNING [SECURITY] then raises
  #     MailThrottledError. The caller decides how to back off.
  #   - warn: emits WARNING [SECURITY] then drops the mail silently
  #     (returns the built message without sending).
  #   - drop (silent) is INTENTIONALLY REJECTED at init: a security
  #     event must never be silent (kstlib logging convention).
  #
  # Singleton: a single MailThrottle is shared across all builders that
  # use the same preset, including snapshots taken by the @notify
  # decorator. This prevents bypass via creating many builder instances.
  #
  # Hard limits enforced in code (see kstlib.limits):
  #   - rate: 1 to 1000 mails per period
  #   - per: 1.0 to 86400.0 seconds (1 day)
  #   - on_exceed: "raise" or "warn"
  throttle:
    enabled: true
    rate: 20
    per: 60.0
    on_exceed: raise

  # SSL/TLS configuration for mail transports.
  #
  # Values here override the root ``ssl:`` section (bottom of this file)
  # for mail only, and are themselves overridden by ``ssl_verify`` and
  # ``ssl_ca_bundle`` keys set inside an individual preset. Each key
  # cascades independently: you can set ``verify: false`` here and still
  # provide ``ssl_ca_bundle`` at the preset level.
  #
  # Security: setting ``verify: false`` at any level emits a WARNING log
  # at transport build time. Prefer ``ca_bundle: /path/to/private-ca.pem``
  # for internal PKI rather than disabling verification outright.
  ssl:
    verify: true
    ca_bundle: null

  # Named transport presets. Each preset declares a "transport" field
  # (smtp or resend) and backend-specific parameters. Define your own
  # presets here and reference them via MailBuilder(preset="name").
  presets: {}
  # Example presets:
  #
  # corporate:
  #   transport: smtp
  #   host: smtp-secure.corp.local
  #   port: 25
  #   login: svc_mail
  #   password: "secret"
  #   starttls: false
  #   ssl: false
  #   timeout: 30
  #   # Optional SSL overrides for this preset (highest priority in the cascade):
  #   ssl_verify: false
  #   ssl_ca_bundle: /etc/ssl/certs/corp-ca.pem
  #   # Optional envelope defaults (sender / reply_to only, never to/cc/bcc):
  #   defaults:
  #     sender: "Service Notifications <notify@corp.local>"
  #     reply_to: "Service Notifications <notify@corp.local>"
  #   # Optional throttle override (highest priority, see mail.throttle above):
  #   throttle:
  #     rate: 5            # corporate is more restrictive than mail-wide default
  #     per: 60.0
  #     on_exceed: warn    # operational critical, prefer drop+log over raise
  #
  # transactional:
  #   transport: resend
  #   api_key: re_xxxxxxxxxxxxx
  #   timeout: 30
  #
  # local:
  #   transport: smtp
  #   host: localhost
  #   port: 1025
  #   starttls: false

  # Attachment and message limits
  limits:
    # Maximum size for a single attachment
    # Accepts: bytes (int) or human-readable string ("25M", "10 MiB")
    # Hard limit enforced in code: 25 MiB
    max_attachment_size: "25M"
    # Maximum number of attachments per message
    # Hard limit enforced in code: 50
    max_attachments: 20

  filesystem:
    attachments_root: "~/.cache/kstlib/mail/attachments"
    inline_root: "~/.cache/kstlib/mail/inline"
    templates_root: "~/.cache/kstlib/mail/templates"
    allow_external_attachments: false
    allow_external_templates: false
    auto_create_roots: true
    enforce_permissions: true
    max_permission_octal: 448 # 0o700

###########################################################################################
## Secrets configuration
###########################################################################################
secrets:
  name: "default"
  providers:
    - name: environment
      settings:
        prefix: "KSTLIB"
        delimiter: "__"
    - name: keyring
      settings:
        service: "kstlib"
  sops:
    # Path to the encrypted secrets file (set to null to disable by default)
    path: null
    # Override the sops executable if it is not on PATH
    binary: "sops"
    # autodetect | json | yaml | text
    format: "auto"
    # Maximum cached decrypted files (LRU eviction)
    # Hard limit enforced in code: 256
    max_cache_entries: 64

###########################################################################################
## Authentication configuration (OAuth2/OIDC)
###########################################################################################
auth:
  # Default provider to use when none specified
  default_provider: null

  # Token storage backend: "memory" (dev/testing), "file" (persistent), or "sops" (encrypted)
  token_storage: "memory"

  # OIDC discovery document cache TTL (seconds)
  discovery_ttl: 3600

  # TRACE level HTTP logging settings
  trace:
    # Pretty-print JSON bodies in TRACE logs (indent with 2 spaces)
    pretty: true
    # Maximum body length before truncation (chars)
    # TRACE = debug mode, show full body by default
    # Hard limit enforced in code: 10000 (10KB)
    max_body_length: 10000

  # Local callback server for authorization code flow
  callback_server:
    host: "127.0.0.1"
    port: 8400
    # Port range to try if primary port is busy (optional)
    port_range: null # e.g., [8400, 8410]
    # Timeout waiting for callback (seconds)
    # Hard limit enforced in code: 600 (10 minutes)
    timeout: 120

  # Status display settings (kstlib auth status)
  status:
    # Access token considered "expiring soon" when remaining time < threshold
    # Hard limits enforced in code: min 60s, max 3600s (1 hour)
    expiring_soon_threshold: 120  # seconds (2 minutes)
    # Refresh token considered "expiring soon" when remaining time < threshold
    # Hard limits enforced in code: min 60s, max 172800s (48 hours)
    # Typically higher since refresh tokens can live days/weeks/months
    refresh_expiring_soon_threshold: 600  # seconds (10 minutes)
    # Timezone for displaying timestamps: "local" or "utc"
    display_timezone: "local"

  # Token storage configuration per backend
  storage:
    file:
      directory: "~/.config/kstlib/auth/tokens"
    sops:
      directory: "~/.config/kstlib/auth/tokens"

  # Named providers (empty by default, users define their own)
  providers: {}
  # Example provider configuration:
  # providers:
  #   corporate:
  #     type: "oidc"              # oauth2 | oidc
  #
  #     # OIDC Discovery modes:
  #     # - Auto: only issuer provided, endpoints auto-discovered
  #     # - Hybrid: issuer + some explicit endpoints (explicit wins)
  #     # - Manual: no issuer, all endpoints explicit (no discovery)
  #     issuer: "https://idp.corp.local/realms/main"
  #
  #     client_id: "my-app"
  #     # Secret can be inline or SOPS reference
  #     client_secret: null       # or "sops://secrets/auth.yaml#corporate.client_secret"
  #     scopes:
  #       - openid
  #       - profile
  #       - email
  #
  #     # PKCE enabled by default (recommended for all clients)
  #     pkce: true
  #
  #     # Optional endpoint overrides (auto-discovered if issuer provided)
  #     authorization_endpoint: null
  #     token_endpoint: null
  #     userinfo_endpoint: null
  #     jwks_uri: null
  #
  #     # Custom HTTP headers sent with all IDP requests
  #     # Useful for load balancer validation, tenant routing, etc.
  #     headers: {}
  #     # Example:
  #     # headers:
  #     #   Host: "idp.corp.local"
  #     #   X-Tenant-Id: "corp"
  #
  #     # Provider-specific token storage (overrides global)
  #     token_storage: null       # "memory" | "file" | "sops"

###########################################################################################
## Utilities configuration
###########################################################################################
utilities:
  secure_delete:
    method: "auto"
    passes: 3
    zero_last_pass: true
    chunk_size: 1048576 # 1 MiB

###########################################################################################
## Resilience configuration
###########################################################################################
resilience:
  # --- Core components (used by WebSocket trading bots) ---

  heartbeat:
    # Seconds between heartbeats
    # Hard limits enforced in code: min 1s, max 300s (5 minutes)
    interval: 10

  watchdog:
    # Seconds of inactivity before triggering timeout callback
    # Hard limits enforced in code: min 1s, max 3600s (1 hour)
    timeout: 30

  # --- Advanced components (for REST API calls, order placement) ---
  # Note: WebSocket connections have built-in reconnection logic.
  # These are useful for REST API resilience (e.g., placing orders, account queries).

  shutdown:
    # GracefulShutdown: Orderly cleanup on SIGTERM/SIGINT with prioritized callbacks.
    # Use case: Ensure open orders are cancelled, positions closed before exit.
    # Total timeout for all cleanup callbacks (seconds)
    # Hard limits enforced in code: min 5s, max 300s (5 minutes)
    timeout: 30
    # Exit code when timeout exceeded
    force_exit_code: 1

  circuit_breaker:
    # CircuitBreaker: Fail-fast pattern for external service calls.
    # Use case: REST API calls (order placement, account info) - after N failures,
    # stop calling the failing endpoint and fail immediately until recovery.
    # Failures before opening circuit
    # Hard limits enforced in code: min 1, max 100
    max_failures: 5
    # Cooldown before attempting recovery (seconds)
    # Hard limits enforced in code: min 1s, max 3600s (1 hour)
    reset_timeout: 60
    # Calls allowed in half-open state for testing
    # Hard limits enforced in code: min 1, max 10
    half_open_max_calls: 1

###########################################################################################
## Database configuration
###########################################################################################
db:
  pool:
    # Minimum connections to maintain in pool (0 = lazy pool, on-demand)
    # Hard limits enforced in code: min 0, max 10
    min_size: 1
    # Maximum connections allowed in pool
    # Hard limits enforced in code: min 1, max 100
    max_size: 10
    # Timeout for acquiring a connection (seconds)
    # Hard limits enforced in code: min 1.0, max 300.0 (5 minutes)
    acquire_timeout: 30.0
  retry:
    # Retry attempts on connection failure
    # Hard limits enforced in code: min 1, max 10
    max_attempts: 3
    # Delay between retries (seconds)
    # Hard limits enforced in code: min 0.1, max 60.0
    delay: 0.5

  # SQLCipher encryption (opt-in, requires: pip install kstlib[db-crypto])
  # System deps: libsqlcipher-dev (Debian/Ubuntu), sqlcipher (macOS/brew)
  cipher:
    # Enable SQLCipher encryption (default: false)
    enabled: false
    # Key source: env | sops | passphrase
    # - env: Read from environment variable (key_env)
    # - sops: Read from SOPS-encrypted file (sops_path + sops_key)
    # - passphrase: Direct passphrase (ONLY for development/testing)
    key_source: env
    # Environment variable containing the encryption key
    key_env: "KSTLIB_DB_KEY"
    # SOPS configuration (when key_source: sops)
    sops_path: null
    sops_key: "db_key"
    # Direct passphrase (NEVER use in production)
    passphrase: null

###########################################################################################
## Credentials configuration (multi-source credential resolution)
###########################################################################################
credentials:
  # Credentials are named entries that can be referenced by rapi services.
  # Supported types: env, file, sops, provider
  #
  # Examples:
  #
  # # Type: env - from environment variable
  # github:
  #   type: env
  #   var: "GITHUB_TOKEN"
  #
  # # Type: env - key+secret pair from environment
  # kraken_env:
  #   type: env
  #   var_key: "KRAKEN_API_KEY"
  #   var_secret: "KRAKEN_API_SECRET"
  #
  # # Type: file - from JSON/YAML file with jq-like path extraction
  # azure_cli:
  #   type: file
  #   path: "~/.azure/msal_token_cache.json"
  #   token_path: ".AccessToken.secret"
  #
  # # Type: file - key+secret from file fields
  # api_file:
  #   type: file
  #   path: "~/.config/api_keys.json"
  #   key_field: "api_key"
  #   secret_field: "api_secret"
  #
  # # Type: sops - from SOPS-encrypted file
  # kraken_prod:
  #   type: sops
  #   path: "secrets/kraken.sops.json"
  #   key_field: "api_key"
  #   secret_field: "api_secret"
  #
  # # Type: provider - from kstlib.auth provider (OAuth2/OIDC)
  # corporate:
  #   type: provider
  #   provider: "corporate"

###########################################################################################
## REST API configuration (config-driven HTTP client)
###########################################################################################
rapi:
  # Hard limits enforced in code for deep defense:
  # - timeout: min 1s, max 300s (5 minutes)
  # - max_response_size: max 100M
  # - max_retries: min 0, max 10
  # - retry_delay: min 0.1s, max 60s
  # - retry_backoff: min 1.0, max 5.0
  limits:
    timeout: 30                # Request timeout in seconds
    max_response_size: "10M"   # Maximum response body size
    max_retries: 3             # Retry attempts on failure
    retry_delay: 1.0           # Initial delay between retries (seconds)
    retry_backoff: 2.0         # Exponential backoff multiplier

  # Safeguard configuration for dangerous HTTP methods
  # Endpoints using these methods MUST define a safeguard string
  # to prevent accidental destructive operations
  safeguard:
    # HTTP methods that require a safeguard to be defined on endpoints
    # Default: DELETE and PUT (most destructive operations)
    # Set to empty list [] to disable safeguard requirements
    required_methods:
      - DELETE
      - PUT

  # Pretty-print settings for CLI output
  # Controls formatting of JSON and XML responses in terminal
  pretty_render:
    # JSON indentation (spaces). Set to null or 0 to disable pretty-printing.
    json: 2
    # XML pretty-print. Set to true to enable formatted XML output.
    xml: true

  # API services and their endpoints
  # Define your own APIs here or use external *.rapi.yml files
  api: {}

  # Example: Azure Resource Manager API
    # azure:
    #   base_url: "https://management.azure.com"
    #   credentials: azure_cli      # Reference to credentials section
    #   auth_type: bearer
    #   headers:
    #     X-Custom-Header: "service-value"
    #   endpoints:
    #     list_subscriptions:
    #       path: "/subscriptions"
    #       query:
    #         api-version: "2020-01-01"
    #       headers:
    #         X-Request-ID: "{request_id}"

###########################################################################################
## Alerts configuration (multi-channel alerting)
###########################################################################################
alerts:
  # Hard limits enforced in code for deep defense:
  # - throttle.rate: min 1, max 1000 alerts per period
  # - throttle.per: min 1.0, max 86400.0 seconds (1 day)
  # - throttle.burst: min 1, max rate value

  # Default throttle settings (anti-spam protection)
  throttle:
    rate: 10        # Maximum alerts per period
    per: 60.0       # Period duration in seconds (1 minute)
    burst: 5        # Initial burst capacity

  # Default channel settings
  channels:
    # Timeout for sending alerts (seconds)
    # Hard limits enforced in code: min 1.0, max 120.0
    timeout: 30.0
    # Retry attempts on delivery failure
    # Hard limits enforced in code: min 0, max 5
    max_retries: 2

  presets:
    dev:
      throttle:
        rate: 100     # More lenient for development
        per: 60.0
        burst: 20
      channels:
        timeout: 10.0
        max_retries: 0

    prod:
      throttle:
        rate: 10      # Strict rate limiting
        per: 60.0
        burst: 3
      channels:
        timeout: 30.0
        max_retries: 3

    critical_only:
      throttle:
        rate: 5       # Very strict for critical-only channels
        per: 300.0    # 5 minutes
        burst: 2

###########################################################################################
## Metrics configuration
###########################################################################################
metrics:
  # Enable colored output
  colors: true

  # Output destination: stderr | stdout
  output: stderr

  # Default behavior for @metrics decorator (can be overridden per-call)
  defaults:
    time: true      # Track execution time
    memory: true    # Track peak memory (tracemalloc)
    step: false     # Enable step numbering

  # Step format string
  # Variables: {n} (step number), {title}, {function}, {module}, {file}, {line}
  step_format: "[STEP {n}] {title}"

  # Lap format string (for Stopwatch)
  # Variables: {n} (lap number), {name}
  lap_format: "[LAP {n}] {name}"

  # Title format (auto-generated when no custom title provided)
  # Variables: {function}, {module}, {file}, {line}
  title_format: "{function} [dim green]({file}:{line})[/dim green]"

  # Time display precision (decimal places for seconds)
  time_precision: 3

  # Thresholds for color warnings
  thresholds:
    time_warn: 5           # Warn color if >= 5 seconds
    time_crit: 30          # Critical color if >= 30 seconds
    memory_warn: 100000000 # Warn color if >= 100 MB
    memory_crit: 500000000 # Critical color if >= 500 MB

  # Icons (set to "" to disable)
  icons:
    time: "⏱"
    memory: "🧠"
    peak: "Peak:"    # Text after memory icon

  # Color theme (Rich style names)
  # See: https://rich.readthedocs.io/en/stable/appendix/colors.html
  theme:
    label: "bold green"
    title: "bold white"
    text: "white"
    muted: "dim"
    table_header: "bold cyan"
    time_ok: "cyan"
    time_warn: "orange3"
    time_crit: "bold red"
    memory_ok: "rosy_brown"
    memory_warn: "orange3"
    memory_crit: "bold red"
    step_number: "dim"
    separator: "dim white"

  # Summary display style: table | simple
  summary_style: table

  # Show percentage of total time in summaries
  show_percentages: true

  # Print metrics to stderr by default
  print_results: true

###########################################################################################
## WebSocket configuration (proactive connection control)
###########################################################################################
websocket:
  # Ping/Pong heartbeat settings
  ping:
    # Seconds between ping frames
    # Hard limits: [5, 60] - values outside bounds will be clamped
    interval: 20
    # Seconds to wait for pong response
    # Hard limits: [5, 30]
    timeout: 10

  # Connection settings
  connection:
    # Timeout for initial connection (seconds)
    # Hard limits: [5, 120]
    timeout: 30

  # Reconnection behavior
  reconnect:
    # Initial delay between reconnect attempts (seconds)
    # Hard limits: [0, 300] - 0 = immediate reconnect allowed
    delay: 1.0
    # Maximum delay for exponential backoff (seconds)
    # Hard limits: [1, 600]
    max_delay: 60.0
    # Maximum consecutive reconnection attempts
    # Hard limits: [0, 100] - 0 = no retry
    max_attempts: 10

  # Message queue settings
  queue:
    # Maximum messages in queue (0 = unlimited)
    # Hard limits: [0, 10000]
    size: 1000

  # Proactive control settings (KEY FEATURE)
  proactive:
    # Seconds between should_disconnect callback checks
    # Hard limits: [1, 60]
    disconnect_check_interval: 10.0
    # Seconds between should_reconnect callback checks
    # Hard limits: [0.5, 60]
    reconnect_check_interval: 5.0
    # Disconnect X seconds before 24h limit (Binance, etc.)
    # Hard limits: [60, 3600] - at least 1min, max 1h
    disconnect_margin: 300.0

  # Presets for common use cases
  presets:
    trading:
      ping: { interval: 15, timeout: 10 }
      reconnect: { delay: 0.5, max_delay: 30.0, max_attempts: 20 }
      proactive: { disconnect_check_interval: 5.0, reconnect_check_interval: 2.0 }
    monitoring:
      ping: { interval: 30, timeout: 15 }
      reconnect: { delay: 5.0, max_delay: 120.0, max_attempts: 50 }
      proactive: { disconnect_check_interval: 30.0, reconnect_check_interval: 10.0 }

###########################################################################################
## Pipeline configuration (declarative workflow execution)
###########################################################################################
pipeline:
  # Default step timeout in seconds
  # Hard limits enforced in code: min 1s, max 3600s (1 hour)
  default_timeout: 300

  # Error handling policy: fail_fast | continue
  # fail_fast: abort pipeline on first step failure (run on_failure steps)
  # continue: execute all remaining steps even after failure
  on_error: fail_fast

  # Named pipelines (user-defined)
  pipelines: {}
    # Example pipeline configuration:
    # morning-monitoring:
    #   steps:
    #     - name: build_logs
    #       type: shell
    #       command: |
    #         for host in server1 server2; do
    #           ssh $host "systemctl status viya"
    #         done
    #       timeout: 300
    #     - name: process_data
    #       type: python
    #       module: my.analytics.runner
    #       args: ["--output", "report.html"]
    #     - name: notify
    #       type: callable
    #       callable: my.alerts:send_summary
    #       when: always
    #     - name: cleanup
    #       type: shell
    #       command: "rm -f /tmp/pipeline_*.tmp"
    #       when: on_failure

# ============================================================================
# OPS - Session Management Configuration
# ============================================================================
# Config-driven session management for persistent processes (bots, services).
# Supports tmux (local dev) and container (Podman/Docker) backends.
#
# Hard limits enforced:
#   - Session name: max 64 chars, alphanumeric + underscore + hyphen
#   - Image name: max 256 chars, valid OCI format
#   - Volumes: max 20, no path traversal
#   - Ports: max 50, range 1-65535
#   - Env vars: max 100, key max 128 chars, value max 32KB
#   - Command: max 4096 chars, dangerous patterns blocked
# ============================================================================
ops:
  # Default backend when not specified (tmux | container)
  default_backend: tmux

  # Tmux binary path (default: tmux)
  tmux_binary: tmux

  # Container runtime (podman | docker | null for auto-detect)
  container_runtime: null

  # Pre-defined sessions (config-driven)
  # Sessions can be started with: kstlib ops start <name>
  sessions: {}
    # Example session configuration:
    # mybot:
    #   backend: tmux                    # Override default_backend
    #   command: "python -m mybot.main"  # Command to run
    #   working_dir: "/opt/mybot"        # Working directory
    #   env:                             # Environment variables
    #     BOT_ENV: production
    #     LOG_LEVEL: INFO
    #
    # mybot-prod:
    #   backend: container
    #   image: "mybot:latest"            # Container image (required)
    #   volumes:                         # Volume mounts (host:container[:ro|:rw])
    #     - "./data:/app/data"
    #     - "./logs:/app/logs:rw"
    #   ports:                           # Port mappings (host:container[/tcp|/udp])
    #     - "8080:80"
    #   log_volume: "./logs:/app/logs"   # Persistent logs for post-mortem

###########################################################################################
## SSL/TLS configuration (global settings for all HTTP clients)
###########################################################################################
ssl:
  # Enable SSL certificate verification (default: true)
  # Set to false ONLY for development with self-signed certificates
  # WARNING: Disabling verification exposes you to MITM attacks
  verify: true

  # Custom CA bundle path for corporate PKI or self-signed certificates
  # If provided, ssl_verify is implicitly true
  # Accepts: null (use system CAs), or path to PEM file
  ca_bundle: null

Common Patterns¶

Development vs Production¶

import os
from kstlib.config import load_from_file

env = os.getenv("APP_ENV", "development")
config = load_from_file(f"config/{env}.yml")

Override from environment¶

# Load base config, then override specific values
config = ConfigLoader().config

# Override at runtime (config is a Box, so this works)
if os.getenv("DEBUG"):
    config.app.debug = True

Testing with isolated config¶

from pathlib import Path
from kstlib.config import clear_config, load_from_file

def test_custom_config(tmp_path: Path):
    config_file = tmp_path / "test.yml"
    config_file.write_text("""
    app:
      debug: true
    """)

    clear_config()  # Isolate from other tests
    config = load_from_file(config_file)

    assert config.app.debug is True

Advanced: AutoDiscoveryConfig¶

Bundle discovery settings into a reusable object:

from pathlib import Path
from kstlib.config import ConfigLoader
from kstlib.config.loader import AutoDiscoveryConfig

auto = AutoDiscoveryConfig(
    enabled=True,
    source="file",
    filename="kstlib.conf.yml",
    env_var="APP_CONFIG",
    path=Path("/srv/kstlib/prod.yml"),
)

loader = ConfigLoader(auto=auto)
config = loader.config

Troubleshooting¶

ConfigFileNotFoundError¶

File doesn’t exist at the specified path:

from kstlib.config import load_from_file
from kstlib.exceptions import ConfigFileNotFoundError

try:
    config = load_from_file("config.yml")
except ConfigFileNotFoundError:
    # Fall back to defaults or create config
    config = bootstrap_defaults()

ConfigFormatError¶

Invalid syntax or parse error in config file:

from kstlib.exceptions import ConfigFormatError

try:
    config = load_from_file("config.yml")
except ConfigFormatError as exc:
    raise SystemExit(f"Invalid configuration: {exc}")

ConfigCircularIncludeError¶

Include loop detected (A includes B, B includes A):

# This will fail
# a.yml includes b.yml, b.yml includes a.yml

Fix: Review your include chain and remove the circular dependency.

Config not updating after file change¶

Config is cached by default. In interactive sessions, force a reload with reload_config():

from kstlib.config import reload_config

config = reload_config()  # Flush cache + reload from disk

See Interactive usage (Jupyter / REPL) for the full discussion and alternatives.

Environment variable not found¶

When using auto_source="env", ensure the variable is set:

export CONFIG_PATH=/path/to/config.yml

# This fails if CONFIG_PATH is not set
config = ConfigLoader(auto_source="env").config

API Reference¶

Full autodoc: Configuration Loader

Function	Description
`ConfigLoader()`	Main loader class with auto-discovery
`load_from_file(path)`	Load from specific file
`get_config()`	Get cached config (singleton)
`clear_config()`	Clear the config cache
`reload_config()`	Flush cache + reload from disk (Jupyter/REPL)

Path resolution in configuration¶

When a configuration value is a filesystem path, for example ssl_ca_bundle, attachments_root, credentials.path, or logging.handlers.file.path, kstlib resolves it with Python’s standard path logic:

Absolute paths are used as-is: /etc/ssl/certs/corp-ca.pem
Tilde-prefixed paths are expanded to the user’s home: ~/ca-bundles/corp.pem becomes /home/alice/ca-bundles/corp.pem
Relative paths are resolved against the current working directory of the Python process, NOT the directory of the YAML file that declared the path.

Why this matters¶

Point 3 is a common source of surprise, especially in interactive environments such as Jupyter:

You have ssl_ca_bundle: ./corp-ca.pem in your config, with corp-ca.pem sitting next to your notebook file.
Your JupyterHub launches the kernel with cwd=/home/alice, which does not contain the file.
kstlib raises MailConfigurationError: ssl_ca_bundle path does not exist: ./corp-ca.pem.

The same trap applies to scripts launched by cron, systemd units, container entry points, or any process whose cwd does not match the directory holding the YAML file.

Recommended practice¶

Always use absolute paths or home-expanded paths in your YAML:

mail:
  presets:
    corporate:
      ssl_ca_bundle: /etc/ssl/certs/corp-ca.pem         # absolute
      # or
      ssl_ca_bundle: ~/.config/kstlib/corp-ca.pem       # home-expanded

Absolute paths are unambiguous across Jupyter, scripts, scheduled jobs, and container processes.

Debugging a relative path¶

If you must use a relative path, verify the Python process cwd:

import os

print(f"Process cwd: {os.getcwd()}")

The relative path is resolved against this value. If the printed cwd differs from where your YAML and its referenced files sit, the path will not resolve. Either os.chdir(...) before the import, or switch to an absolute path.

Future direction¶

Resolving relative paths against the YAML file that declared them is a candidate enhancement on the backlog (tracked as feat-config-paths-relative-to-yaml). Implementing it requires kstlib to track, for every configuration value, the file it originated from, which is a substantial refactor of the loader. For now, use absolute paths to avoid ambiguity across different execution contexts.

Configuration¶

TL;DR¶

Key Features¶

Quick Start¶

How It Works¶

Loading Strategies¶

System-Wide Configuration¶

Default paths per OS¶

Linux: XDG_CONFIG_DIRS semantics¶

Full cascade at a glance¶

Example: corporate baseline + user overrides¶

Opting out¶

Include System¶

Supported Formats¶

Caching¶

Interactive usage (Jupyter / REPL)¶

Configuration¶

CLI Export¶

Environment-Based Structure¶

Strict Format Mode¶

Default Configuration¶

Common Patterns¶

Development vs Production¶

Override from environment¶

Testing with isolated config¶

Advanced: AutoDiscoveryConfig¶

Troubleshooting¶

ConfigFileNotFoundError¶

ConfigFormatError¶

ConfigCircularIncludeError¶

Config not updating after file change¶

Environment variable not found¶

API Reference¶

Path resolution in configuration¶

Why this matters¶

Recommended practice¶

Debugging a relative path¶

Future direction¶

Linux: `XDG_CONFIG_DIRS` semantics¶