Introduction

In Python signatures, a slash indicates positional-only parameters. Any parameter to the left of that slash must be passed by position, not by keyword. This notation often appears in help() and inspect output for built-ins and low-level APIs.

Signature Markers You Should Know

Python uses two boundary markers for call conventions:

• / marks the end of positional-only parameters.
• * marks the beginning of keyword-only parameters.

Example:

1def f(a, b, /, c, *, d):
2    return a, b, c, d
3
4print(f(1, 2, 3, d=4))

Meaning:

• a and b are positional-only.
• c can be positional or keyword.
• d must be keyword-only.

Why Positional-Only Exists

This feature exists for practical API design reasons, not syntax novelty.

Benefits:

• Prevents external code from depending on internal parameter names.
• Allows maintainers to rename parameter identifiers safely.
• Aligns user-defined APIs with built-in behavior.
• Avoids naming collisions in dictionary-like interfaces.

For stable libraries, positional-only arguments can reduce long-term compatibility burden.

How It Appears in help() Output

Built-ins and C-implemented functions commonly show slash notation.

help(divmod)
help(pow)

When help() displays /, read it as a strict calling rule. It is not documentation decoration.

If callers pass positional-only args as keywords, Python raises a TypeError.

Designing Your Own Function with /

From Python 3.8 onward, you can define positional-only params explicitly.

1def scale(value, factor, /, precision=2):
2    return round(value * factor, precision)
3
4print(scale(3.5, 1.2))
5print(scale(3.5, 1.2, precision=3))

Here value and factor cannot be named at call-site, while precision remains flexible.

Balancing API Stability and Readability

You should not add positional-only markers everywhere. Use them where signature stability matters more than keyword readability.

Good candidates:

• Low-level utility functions.
• Performance-sensitive wrappers around built-ins.
• APIs where parameter names are implementation details.

Less ideal candidates:

• Business-facing APIs where keyword clarity improves maintainability.

A balanced style guide prevents both overuse and underuse.

Migration and Compatibility Concerns

Adding / to an existing public function can break callers that currently use keywords. Treat this as a compatibility change.

Safe migration strategy:

1. Audit existing call patterns.
2. Announce change in release notes.
3. Introduce in a major version if public API is widely used.

Call convention changes should be reviewed with the same rigor as return-type changes.

Introspection and Framework Integration

Frameworks that validate callbacks often rely on signature metadata. inspect.signature preserves slash notation and can be used for defensive checks.

1import inspect
2
3def g(x, y, /, z):
4    return x + y + z
5
6print(inspect.signature(g))

If your framework auto-binds keyword arguments, this detail matters for preventing runtime call errors.

Error Interpretation

Common error:

TypeError: f() got some positional-only arguments passed as keyword arguments

When this appears:

• Inspect function signature.
• Move left-of-slash args to positional order.
• Keep keywords for parameters to the right of slash.

Most slash-related issues are resolved quickly once call ordering is corrected.

A useful team habit is to include signature examples in docstrings for public functions that use slash notation, so call rules are visible during code review.

Common Pitfalls

• Assuming every parameter in Python can be passed by keyword.
• Confusing slash marker behavior with star marker behavior.
• Overusing positional-only constraints in high-level APIs.
• Changing call conventions in stable APIs without version planning.
• Wrapping built-ins but forgetting to preserve their call semantics.

Summary

• Slash in Python signatures marks positional-only parameters.
• Parameters to the left of / cannot be passed as keywords.
• The marker is common in built-ins and available in user functions.
• Use it intentionally for API stability, not as default style.
• Understand / together with * to design clear call contracts.