kwargs in Python: Collect, Forward and Validate Named Options

Start with a small, explicit task

Build a fictional label renderer with two allowed options: prefix and uppercase. Forward them through a preview helper, check that the caller’s options mapping is unchanged, and reject an unsupported spelling. The options affect returned text only; they do not configure a global display system.

Run the complete example

This original example was checked with Python 3.12.14. Save it as python_kwargs.py and run it with Python 3.12. It uses only the standard library. The assertions check the stated results.

def render_label(text, **kwargs):
    unknown = set(kwargs) - {"prefix", "uppercase"}
    if unknown:
        raise TypeError("unsupported options: " + ", ".join(sorted(unknown)))
    prefix = kwargs.get("prefix", "")
    uppercase = kwargs.get("uppercase", False)
    return prefix + (text.upper() if uppercase else text)
def preview(text, **options):
    return render_label(text, **options)
options = {"prefix": ">> ", "uppercase": True}
result = preview("ready", **options)
assert result == ">> READY"
assert options == {"prefix": ">> ", "uppercase": True}
assert render_label("ready") == "ready"
try:
    preview("ready", uppercas=True)
except TypeError as exc:
    failure = str(exc)
else:
    raise AssertionError("expected unsupported option")
assert failure == "unsupported options: uppercas"
print(result)
print(failure)

Explain the result

The caller expands options into named arguments. preview collects them into its own options dictionary and expands them again when calling render_label. The renderer collects its extras as kwargs and explicitly permits only two names. The caller’s original mapping remains unchanged in the assertion.

The misspelled uppercas is not silently ignored, so a caller sees why its requested formatting did not apply. This validation checks option names, not a complete type schema: the example assumes a string prefix and a boolean uppercase option. If a real interface accepts arbitrary external data, validate the option value types as well.

Avoid these mistakes

A function that accepts **kwargs is not automatically a flexible, safe public API. Named parameters can be clearer for a small fixed set of options. Also avoid supplying the same named argument both explicitly and through an unpacked mapping, which can produce a duplicate-argument TypeError.