Support positional-only arguments in the strict sense

[maread99]

Summary

Previously valimp ignored any / in a decorated function's signature, allowing arguments intended to be positional-only to be passed as keyword arguments.

valimp now enforces positional-only arguments in the strict sense: a positional-only argument can only be passed positionally. Passing it by keyword raises an InputsError, unless the signature provides for **kwargs, in which case the keyword input is absorbed by **kwargs — consistent with standard Python behaviour.

Behaviour

@parse
def f(a: int, b: str, /, c: int): ...

f(1, "x", 3)        # ok
f(1, "x", c=3)      # ok (c is positional-or-keyword)
f(a=1, b="x", c=3)  # InputsError: Got positional-only argument as keyword argument (and signature makes no provision for **kwargs that would otherwise receive it): 'a'.

@parse
def g(a: int, /, **kwargs: int): ...

g(1, a=2, b=3)      # ok -> a=1, kwargs={'a': 2, 'b': 3}  (matches plain Python)
g(a=2)              # InputsError: Missing 1 positional argument: 'a'.

Implementation

• The check lives in validate_against_signature alongside the other signature checks. It receives the positional-only parameter names and those invalidly received as keyword arguments, reporting the latter via a dedicated "Received positional-only argument(s) as keyword argument(s): ..." error.
• inspect.signature is interrogated to identify positional-only parameters, since inspect.getfullargspec does not distinguish them (they are lumped into spec.args).
• In wrapped_f, any keyword input matching a positional-only parameter name is removed from kwargs up front (held as kwarg_name_as_posonly): it never binds to the parameter. With no **kwargs it raises; otherwise it is absorbed into **kwargs, and a required positional-only parameter not also passed positionally is still correctly reported as missing.
• Values absorbed by **kwargs under a positional-only name are validated, coerced and parsed against the **kwargs annotation. Their errors are filed under a disambiguated key (e.g. "a (**kwargs)") so an absorbed value's error never silently overrides the positionally-received argument's error — both are reported when both are invalid.
• The reconstruction loop's coerce/parse logic was factored into a reusable apply_coerce_and_parser helper so absorbed **kwargs values are handled consistently with other inputs.

Documentation

• The "does not currently support positional-only arguments" note was removed from the module docstring and README.
• The README public_function example and the tutorial's "Signature validation" section now demonstrate positional-only support (and the new keyword-rejection error), with positional-only listed under the README's "What's supported".

Testing

• Added tests covering: passing positional-only args positionally (incl. coerce/parse); the single- and multiple-argument keyword-rejection errors; interaction with other signature errors; **kwargs absorption (with and without a default); the required-but-missing case; validation/coercion of absorbed values and the doubly-invalid name-collision case; and a decorated method.
• pytest: all tests pass. ruff check / ruff format: clean. mypy: no new errors.

---

Generated by Claude, manually fully reviewed and notably revised.
Generated by Claude Code