positionalonly 0.0.3

positionnal only arguments/parameters

positionnal only arguments/parameters

Module to fake positional only arguments (pep 497, Draft).

Let’s take the following function as example:

def diff(left, right, context=3):
'''print the diff between `left` and `right` with `context`
'''
...

right and left are now part of the API, and users may decide to use diff(left=str1, right=str1), blocking api changes, so you can’t change the names of the parameters, to for example def diff(old, new, context=3) without using the C-api.

This module provide a decorator @positionalonly to make all the default-less parameters of your function positional only, so you can write:

@positionalonly
def diff(left, right, context=3):
...

Usingit like will raise a TypeError, and the function signature will use the positional only argument syntax with the / of pep 497.

>>> diff(right="bar", left="foo")
TypeError: The following parameters of `diff` are positional only.
They were used as keywords arguments:
- 'right' ('bar') should be in 2nd position
- 'left' ('foo') should be in 1st position

>>> help(diff)
Help on function diff in module __main__:

diff(left, right, /, context=3)

Advanced usage

By default positionalonly will make the limit between positional-only and the rest of the arguments just before the first argument with default. You can tweek this behavior by passing an integer as parameter indicating the number of argument to make positional-only:

>>> @positionalonly(3)
... def diff(old, new, context=3)
... pass

>>> signature(diff)
diff(left, right, context=3, /)


>>> @positionalonly(1)
... def diff(old, new, context=3)
... pass

>>> signature(diff)
diff(left, /, right, context=3)

If you are too lazy to count, or are afraid of misscounting, positionalonly will also decide to put the limit to the first argument which default value is positionalonly itself.

>>> @positionalonly
... def diff(old, new, end=positionalonly, context=3)
... pass

>>> signature(diff)
diff(left, right, /, context=3)

>>> pos_or_kw
>>> @positionalonly
... def diff(old, start=pos_or_kw, context=3)
... pass

>>> signature(diff)
diff(left, /, right, context=3)

Reasons to use positional only

Naming of argument, and in particular the function signature can be helfull for tab completion, and static analysis to understand the code. While posistional only is usable using *args it hides all this information both from the human and the computer.

The default behavior of Python, is to make agument by dafult, positional an keyword.

This fact often prevent the developer from changing the name without breaking the API.

This also prevent arbitrary **kwargs keys as they are be taken by “positionaly or keyword” arguments.