TRENDING

TECHNOLOGY NEWS FROM AROUND THE WORLD

→
Python 3.8 positional-only parameters and a stable API contract
Software Engineering · 2019
Software Engineering2019

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.

Yazılımcının GünlüğüPublished: Nov 18, 20263 min read
Reading progress0%

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.

Service architectureConceptual sketch · summary of the article's technical flow
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.

Be the first reader ✎ Write a comment

Comments

No comments yet. Be the first to contribute.

Robin Bennett

Reading “Python 3.8 positional-only parameters and a stable API contract” raised this question for me: migration and rollback plans should be explained.

Sample editor reply

Editor note: Forward-looking claims in an announcement are not the same as established performance results. Further evidence may change the assessment.

Cameron Hayes

It is important to distinguish what the source verifies from projections about the future.

Sidney Wood

The next version's measurements should be compared with the initial announcement.

✎ Write a comment

Your first and last name will appear publicly alongside your comment.