Introduction

Forcing callers to name arguments can make APIs clearer and safer, especially when several parameters have similar types or meanings. In Python, the direct tool for this is keyword-only parameters. Instead of relying on convention alone, you can design the function signature so positional calls are rejected automatically.

Force names with keyword-only parameters

In Python, put * before the first parameter that must be passed by name.

1def connect(*, host, port, timeout=10):
2    return f"{host}:{port} timeout={timeout}"
3
4print(connect(host="localhost", port=5432))

This works because host, port, and timeout are keyword-only.

A positional call fails:

1def connect(*, host, port):
2    return f"{host}:{port}"
3
4# TypeError
5# connect("localhost", 5432)

That is the standard Python answer when you want to force named arguments at the call site.

Mix positional and keyword-only parameters

Sometimes only part of the signature needs forced naming. Python allows a hybrid design.

1def resize(image_path, *, width, height, keep_aspect_ratio=True):
2    return (image_path, width, height, keep_aspect_ratio)
3
4print(resize("photo.jpg", width=800, height=600))

Here image_path may be positional, while the configuration parameters must be named. This is often a good balance between convenience and readability.

Why this improves API quality

Named arguments help when values are easy to mix up:

1def create_user(*, name, age, is_admin=False):
2    return {"name": name, "age": age, "is_admin": is_admin}
3
4user = create_user(name="Mina", age=30, is_admin=True)
5print(user)

Compare that with a positional-only style such as create_user("Mina", 30, True). The named version is more self-documenting and less likely to be called incorrectly months later.

This matters most when:

• Parameters have the same type
• Several optional flags exist
• Wrong order can still produce syntactically valid code

Enforcing names without * is usually the wrong route

You could manually inspect *args and **kwargs and raise your own errors, but that is unnecessary when the language already provides keyword-only parameters.

The built-in signature mechanism gives you:

• Better error messages
• Cleaner function definitions
• Better tooling support
• More accurate introspection

Use the language feature first. Manual argument policing is rarely an improvement here.

Compare with positional-only parameters

Python also supports the opposite concept: positional-only parameters, marked with /.

def ratio(x, y, /):
    return x / y

That means callers cannot write ratio(x=10, y=2). It is useful to know because it shows that Python signatures can express both sides of the contract:

• Parameters that must be positional
• Parameters that must be named

For this question, keyword-only parameters are the tool you want.

Common Pitfalls

The biggest mistake is assuming that default arguments automatically imply named arguments. They do not. A parameter can have a default value and still be positional unless you make it keyword-only.

Another issue is overusing forced naming for trivial APIs. If the function takes one obvious value, requiring a keyword may add noise instead of clarity.

Developers also sometimes write custom argument-validation code when a simple * in the function signature would solve the problem directly.

Finally, be intentional about API evolution. Adding keyword-only parameters can improve readability, but changing an old positional API may break callers if done without planning.

Summary

• In Python, force named arguments with keyword-only parameters.
• Put * before the parameters that must be passed by keyword.
• Mix positional and keyword-only parameters when that makes the API clearer.
• Prefer signature-level enforcement over manual args and kwargs checking.
• Use forced naming where it improves clarity, not just because it is possible.