Target a dependency inside the graph

Prerequisite: flat overrides. The key in the override mapping expresses how to find a constructor socket below the melded root.

Form	Example	Match rule
Exact path	`transport>credentials`	The named socket path
Unique wildcard	`*credentials`	Exactly one matching socket
Broadcast	`**credentials`	At least one matching socket; apply to all matches

The wildcard lesson exercises one match, multiple matches, no matches, and overlap. When a broadcast and exact path name the same socket, the exact path takes precedence. The complete example keeps its objects many so later melds construct clean graphs.

Targeting and lifetime are separate decisions

The deep-path lesson deliberately uses unique. Its override helps construct a singleton transport, and a later plain meld retrieves that same transport with the injected credentials still inside it. The substitution lasts as long as the object it helped create. It is not automatically limited to the duration of a call.

Run both examples: the first demonstrates this lifetime consequence; the second demonstrates the match grammar and fresh-instance contrast.

The workflow in code

These are the core steps from the saved example. Use its complete linked script for all class definitions and setup.

def main() -> None:
    conduit = _book().conjure(name="override-root")

    fixture = Credentials()
    fixture.source = "test-fixture"

    # UNIQUE - *param. MailPipeline has exactly ONE credentials socket
    # under it, so the wildcard resolves without naming the path.
    mail = conduit.meld(
        "MailPipeline",
        override={"*credentials": fixture},
    )
    assert mail.transport.credentials is fixture
    print("*credentials found the single socket:",
          mail.transport.credentials.source)

    # ...and the same spec against a root with TWO matching sockets is
    # REFUSED. "exactly one" is a requirement, not a preference - this is
    # the whole reason the form is safe to reach for.
    try:
        conduit.meld(
            "BackupPipeline",
            override={"*credentials": fixture},
        )
        raise AssertionError("expected a refusal - *param matched twice")
    except Exception as error:
        print("*credentials refused two matches:", type(error).__name__)

    # BROADCAST - **param. Same graph, and now hitting every match is
    # exactly what was asked for.
    backup = conduit.meld(
        "BackupPipeline",
        override={"**credentials": fixture},
    )
    assert backup.transport.credentials is fixture
    assert backup.archive.credentials is fixture
    print("**credentials hit both sockets:",
          backup.transport.credentials.source,
          "/", backup.archive.credentials.source)

    # A broadcast that matches NOTHING is refused too - "at least one" is
    # also enforced. A no-op override is a caller mistake, not a default.
    try:
        conduit.meld(
            "MailPipeline",
            override={"**nosuchparam": fixture},
        )
        raise AssertionError("expected a refusal - **param matched nothing")
    except Exception as error:
        print("**nosuchparam refused zero matches:", type(error).__name__)

    # PRECEDENCE. Broadcast everything, then name one socket exactly - the
    # exact path is MORE SPECIFIC and wins where the two overlap.
    specific = Credentials()
    specific.source = "archive-only"
    mixed = conduit.meld(
        "BackupPipeline",
        override={
            "**credentials": fixture,
            "archive>credentials": specific,
        },
    )
    assert mixed.transport.credentials is fixture
    assert mixed.archive.credentials is specific
    print("overlap resolved by specificity - transport:",
          mixed.transport.credentials.source,
          "| archive:", mixed.archive.credentials.source)

    # `many` kept the blast radius inside the call: a plain meld gets a
    # clean graph with no fixture in it.
    clean = conduit.meld("BackupPipeline")
    assert clean.transport.credentials is not fixture
    assert clean.archive.credentials.source == "vault"
    print("plain meld is untouched:", clean.archive.credentials.source)

    print()
    print("three forms: exact path, *one, **all - the grammar is in the key")
    print("match counts are ENFORCED - a guessing wildcard would fail silently")

Runnable examples

Wildcard and broadcast overrides — Advanced 19
Deep spell override paths — Advanced 01
Deep overrides paths through a graph — Expert 10

All advanced examples · Level contents · Full contents

Canonical page source