trace

Module to write the source of each function keyword argument for the developer

Example:

$ uv run main.py  # trace_level=DEBUG set in the program
2025-10-14 16:15:33.466 | DEBUG    | argmerge.trace:_write_trace:50 -
Parameter Name  | Source
=======================================
third   | Python Function default
fourth  | Python Function default
fifth   | Python Function default
first   | developer-provided
second  | developer-provided
=======================================

trace_arg_lineage

trace_arg_lineage(f, change_ledger, level='')

Determine where each argument in the function came from.

Only include arguments that exist in the function header. If a function accepts **kwargs and an irrelevant keyword is provided - discard it.

Parameters:

• f (callable) –
• change_ledger (dict) –

  The final dictionary detailing where every argument is set - defaults, files, environment variables, CLI arguments, etc.

Source code in src/argmerge/trace.py

def trace_arg_lineage(
    f: Callable,
    change_ledger: dict[str, dict[str, str | int]],
    level: str = "",
):
    """Determine where each argument in the function came from.

    Only include arguments that exist in the function header. If a function accepts
    **kwargs and an irrelevant keyword is provided - discard it.

    args:
        f (callable):
        change_ledger (dict): The final dictionary detailing where every argument
            is set - defaults, files, environment variables, CLI arguments, etc.
    """
    sig = signature(f)
    _changed = {k: v for k, v in change_ledger.items() if k in sig.parameters}

    _log_trace(ledger=_changed, level=level)