Python 3.8 positional-only parameters and a stable API contract
How Python 3.8's slash syntax affects public function signatures, compatibility reviews and callable tests.
A function signature is a release contract
Python 3.8 added slash notation for positional-only parameters in a function definition. Parameters before the slash cannot be supplied by keyword. Library authors can use this distinction to decide which details callers may rely on. Once a parameter name is part of supported keyword calls, renaming it can break customer code. A deliberately designed signature makes that boundary visible to callers and to anyone reviewing a future change.
Separate the data from configuration
Consider a CSV parsing function whose first value is the input row. The row is recognizable by position, while delimiter and missing-value behavior read clearly as named options. A slash may mark the row as positional-only, and an asterisk can make later options keyword-only. The reverse can be appropriate for two similar values such as a source and target date. Meaningful names help prevent accidental argument swaps.
def read_row(row, /, *, delimiter=","):
return row.split(delimiter)
read_row("id|name", delimiter="|")Review downstream callers before changing an API
Restricting an existing parameter to positional calls breaks users who already call it by keyword. Review examples, plugins, CLI wrappers and other integrations that obtain or call the function indirectly. A new entry point with the desired signature can coexist with an older compatibility wrapper. If the previous API will eventually change, document the behavior that is deprecated as well as the timeline and migration path.
Test both accepted and rejected calls
Write tests that cover the usual positional call, a keyword option and a rejected keyword for a positional-only input. The negative test can assert TypeError without tying itself to interpreter wording. If a decorator wraps the function, compare the displayed signature with its actual behavior. Confirm that generated documentation preserves slash and asterisk markers where relevant.
Choose a convention based on readability
A short position-based call can work when the value is obvious in context. Prefer explicit names for options that change timeout, policy or resulting behavior. The ability to rename a parameter later is only one consideration. In everyday code, descriptive keywords can document decisions at the point of use. Review code examples, type information and contract tests together each time a public signature changes.
Comments
No comments yet. Be the first to contribute.
Reading “Python 3.8 positional-only parameters and a stable API contract” raised this question for me: migration and rollback plans should be explained.
Editor note: Forward-looking claims in an announcement are not the same as established performance results. Further evidence may change the assessment.
It is important to distinguish what the source verifies from projections about the future.
The next version's measurements should be compared with the initial announcement.
✎ Write a comment