How to merge two dicts.
The | operator. Or the unpacking. Or update.

Precedence rule (all methods):

  d1 = {'b': 2}
  d2 = {'b': 99}

  d1 | d2    → {'b': 99}   (right wins)
  {**d1, **d2} → {'b': 99} (right wins)
  d1.update(d2) → d1 is {'b': 99}  (right wins)

To make the left win, reverse:

  d2 | d1    → {'b': 2}
  {**d2, **d1} → {'b': 2}

The rule is consistent: last one wins.
Same as function argument order, or CSS cascade.

Which to use:

✅ Python 3.9+, creating a new dict → use |
   Clearest. Returns a new dict.

✅ Python < 3.9, creating a new dict → use {**d1, **d2}
   Same behavior, just older syntax.

✅ Modifying an existing dict → use .update()
   Returns None. Modifies in place.

✅ Python 3.9+, modifying an existing dict → use |=
   Same as .update(), shorter.

❌ Merging more than two dicts with .update()
   Requires a loop or chain.

❌ Merging without copying, when you need
   a read-only view → use ChainMap.

The pitfall:

  d1 = {'a': 1}
  d2 = {'b': 2}
  d1.update(d2)
  # d1 is now {'a': 1, 'b': 2}
  # If another part of the code has a reference
  # to d1, that reference now sees the merged dict.
  
  # Use | or {**} to avoid this:
  merged = d1 | d2
  # d1 unchanged. merged is new.

The default should be:
  | for new dict, .update() for in-place mutation.
  Choose based on whether other code holds a reference.

The difference:

|  → creates a new dict
     The left operand is unchanged.
     The right operand is unchanged.
     Returns a third, new dict.

|= → mutates the left operand
     The left operand is updated in place.
     The right operand is unchanged.
     Returns the left operand (same object).

When to use which:

✅ | — when the caller shouldn't see changes
   Function returns a merged dict without
   modifying the input.
   
   def merge_config(base, overrides):
       return base | overrides

✅ |= — when the caller expects changes
   In-place update of a settings dict.
   
   def apply_overrides(config, overrides):
       config |= overrides
       # config is now updated, caller sees it

Same for += vs + on lists, sets, and strings.
The augmented assignment mutates; the plain
operator creates a new object.

The rule of thumb:

  If your function accepts a dict argument
  and returns a merged version, use |.
  
  If your function accepts a dict argument
  and modifies it in place (like a settings
  object, cache, or accumulator), use |=.

  The choice signals intent to the caller.

⚠️ Don't mix them:

  ❌ def bad(x):
        x |= something
        return x
     # Modifies the caller's dict AND returns it.
     # Confusing. Pick one behavior.

  ✅ def good(x):
        return x | something
     # Pure function. No mutation.

  ✅ def update_in_place(x):
        x |= something
        # no return (or return None)
     # Clear it's an in-place operation.

The function signature (return value, or
None) should match the behavior (new dict,
or in-place).

ChainMap vs merged dict:

ChainMap:
  → no copy
  → lookups check each dict in order
  → reflects live changes
  → writes go to first dict
  → good for layered config

Merged dict (|, {**}, .update):
  → copies all key-value pairs
  → lookups check the one dict
  → frozen snapshot
  → writes modify the merged dict
  → good for a standalone dict

When to use ChainMap:

✅ Layered configuration:
   defaults + user + env overrides
   → no need to copy defaults into user

✅ Temporary views:
   "show me the current config"
   → reflects changes without re-merging

✅ Read-heavy code:
   If you look up keys many times, ChainMap's
   no-copy is faster than merging once.

✅ Large dicts:
   For a 1 MB dict, merging copies 1 MB.
   ChainMap references, no copy.

When NOT to use ChainMap:

❌ You need a standalone dict.
   ChainMap is a view, not a dict.
   Pass it to code that expects a dict,
   and it may not work.

❌ You need to write to specific dicts.
   Writes go to the first dict only.
   To write to a different dict, use .maps[i].

❌ You need performance on reads.
   Actually — ChainMap is fast on reads.
   But it's slower than a single dict,
   because each miss checks the next dict.
   For a small number of dicts, no problem.
   For hundreds, use a merged dict.

The common ChainMap pattern:

  from collections import ChainMap

  def get_config():
      defaults = {'debug': False, 'port': 8080}
      user = load_user_config() or {}
      env = {
          k: v for k, v in os.environ.items()
          if k.startswith('APP_')
      }
      return ChainMap(env, user, defaults)

  config = get_config()
  config['port']  # env wins, then user, then defaults

  # All three dicts are visible.
  # Changes to env/user/defaults are reflected.
  # Reads are O(len(dicts)), not O(1).
  # Fine for 3-5 layers of config.

For most merging tasks, use |.
ChainMap is for the specific pattern of
"layered lookups without copying."
If you don't need that, don't use it.