Merging#

How Merging Works#

graph TD
    S1["Source 1"] --> R1["Read source data"]
    S2["Source 2"] --> R2["Read source data"]
    SN["Source N"] --> RN["Read source data"]

    R1 --> SK1{"skip_invalid_fields?"}
    SK1 -- yes --> D1["Drop fields that fail\ntype or constraint check"] --> M["Apply merge strategy\n(last_wins / first_wins / …)"]
    SK1 -- no --> HV1{"Has field\nvalidators?"}
    HV1 -- yes --> FP1["Validate fields\nprovided by this source"] --> M
    HV1 -- no --> M

    R2 --> SK2{"skip_invalid_fields?"}
    SK2 -- yes --> D2["Drop fields that fail\ntype or constraint check"] --> M
    SK2 -- no --> HV2{"Has field\nvalidators?"}
    HV2 -- yes --> FP2["Validate fields\nprovided by this source"] --> M
    HV2 -- no --> M

    RN --> SKN{"skip_invalid_fields?"}
    SKN -- yes --> DN["Drop fields that fail\ntype or constraint check"] --> M
    SKN -- no --> HVN{"Has field\nvalidators?"}
    HVN -- yes --> FPN["Validate fields\nprovided by this source"] --> M
    HVN -- no --> M

    M --> FGR["field_groups: enforce that related fields\nare all set by the same source"]
    FGR --> FMR["field_merges: combine field values\nacross sources (e.g. merge lists)"]
    FMR --> CONSTR["Construct dataclass\n+ run all validators\n(root_validators + Annotated on defaults)"]
    CONSTR --> D["Dataclass"]

When your config is spread across several sources — defaults in a file, overrides from the environment, and so on — dature loads each source independently, layers them by priority, and produces one validated instance. Crucially, each source is validated on its own contribution, so an override only needs to be valid for the fields it actually sets.

1. Load and validate each source independently. Every source is read (with expand_env_vars substitution and mask_secrets / secret_field_names masking). If skip_invalid_fields is on, invalid values are dropped per source before field validation. Then each source's own values are coerced and run through field-level validation — type coercion, Annotated constraints, source-level validators=. A source is judged only on the fields it provides, never on the merged whole. Missing or broken sources can be tolerated with skip_if_missing / skip_if_broken; first_found tolerates them automatically.
2. Layer the sources together (strategy). Sources are merged by the chosen strategy: last_wins (default — later sources override earlier), first_wins (earlier sources win), first_found (take the first that loads, ignore the rest), or raise_on_conflict (error if two sources disagree on a value). Nested sections merge key-by-key; lists and scalars are replaced wholesale according to the strategy.
3. Apply cross-source rules. field_groups= enforce that related fields are always overridden together — never half from one source, half from another. field_merges= apply per-field aggregation (e.g. concatenating lists or picking the max) instead of a plain last/first-wins replacement.
4. Construct and validate dataclass. The merged values are assembled into the instance. root_validators= run once on the finished object — checks that span several fields at once (e.g. "start must be before end"). Fields no source supplied take their dataclass defaults; any Annotated constraints on those defaults are still enforced.
5. Result. One typed, validated config — or a report of every problem, each tied to the source it came from.

Steps 4–5 are identical to single-source loading: multi-source is just single-source with a per-source load-and-validate step and a merge step in front. One source is the N=1 case.

Basic Merging#

Pass multiple Source objects to dature.load():

from dataclasses import dataclass

import dature


@dataclass
class Config:
    host: str
    port: int
    tags: list[str]


config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_defaults.yaml"),
    dature.Yaml12Source(file=SHARED_DIR / "common_overrides.yaml"),
    schema=Config,
    strategy="last_wins",
)

assert config.host == "production.example.com"
assert config.port == 8080
assert config.tags == ["web", "api"]

host: "localhost"
port: 3000
tags:
  - "default"

host: "production.example.com"
port: 8080
tags:
  - "web"
  - "api"

Multiple Sources#

Multiple sources use "last_wins" by default:

from dataclasses import dataclass

import dature


@dataclass
class Config:
    host: str
    port: int
    tags: list[str]


config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_defaults.yaml"),
    dature.Yaml12Source(file=SHARED_DIR / "common_overrides.yaml"),
    schema=Config,
)

assert config.host == "production.example.com"
assert config.port == 8080
assert config.tags == ["web", "api"]

host: "localhost"
port: 3000
tags:
  - "default"

host: "production.example.com"
port: 8080
tags:
  - "web"
  - "api"

The decorator also uses `"last_wins"``:

import os
from dataclasses import dataclass

import dature

os.environ["APP_HOST"] = "env_localhost"


@dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_defaults.yaml"),
    dature.EnvSource(prefix="APP_"),
)
@dataclass
class Config:
    host: str
    port: int
    debug: bool = False


config = Config()
assert config.host == "env_localhost"
assert config.port == 3000
assert config.debug is False

host: "localhost"
port: 3000
tags:
  - "default"

Merge Strategies#

Nested dicts are merged recursively. Lists and scalars are replaced entirely according to the strategy.

from dataclasses import dataclass

import dature


@dataclass
class Config:
    host: str
    port: int
    tags: list[str]


config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_defaults.yaml"),
    dature.Yaml12Source(file=SHARED_DIR / "common_overrides.yaml"),
    schema=Config,
    strategy="last_wins",
)

assert config.host == "production.example.com"
assert config.port == 8080
assert config.tags == ["web", "api"]

host: "localhost"
port: 3000
tags:
  - "default"

host: "production.example.com"
port: 8080
tags:
  - "web"
  - "api"

from dataclasses import dataclass

import dature


@dataclass
class Config:
    host: str
    port: int
    tags: list[str]


config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_defaults.yaml"),
    dature.Yaml12Source(file=SHARED_DIR / "common_overrides.yaml"),
    schema=Config,
    strategy="first_wins",
)

assert config.host == "localhost"
assert config.port == 3000
assert config.tags == ["default"]

host: "localhost"
port: 3000
tags:
  - "default"

host: "production.example.com"
port: 8080
tags:
  - "web"
  - "api"

from dataclasses import dataclass

import dature


@dataclass
class Config:
    host: str
    port: int
    tags: list[str]


config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "nonexistent.yaml"),
    dature.Yaml12Source(file=SHARED_DIR / "common_defaults.yaml"),
    dature.Yaml12Source(file=SHARED_DIR / "common_overrides.yaml"),
    schema=Config,
    strategy="first_found",
)

assert config.host == "localhost"
assert config.port == 3000
assert config.tags == ["default"]

host: "localhost"
port: 3000
tags:
  - "default"

from dataclasses import dataclass

import dature


@dataclass
class Config:
    host: str
    port: int
    debug: bool


config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_raise_on_conflict_a.yaml"),
    dature.Yaml12Source(file=SHARED_DIR / "common_raise_on_conflict_b.yaml"),
    schema=Config,
    strategy="raise_on_conflict",
)

assert config.host == "localhost"
assert config.port == 3000
assert config.debug is True

host: "localhost"
port: 3000

debug: true

strategy is not limited to the names above — any object implementing the SourceMergeStrategy Protocol is accepted, so you can plug in your own merge logic (e.g. let env sources override files unconditionally) while still composing the built-in strategies. See Custom Source Strategy.

For per-field strategy overrides, see Per-Field Merge Strategies. To enforce that related fields are always overridden together, see Field Groups.

Merge Parameters#

All merge-related parameters are passed directly to dature.load() as keyword arguments: