ENH: Improve typing for decorators that change signature

[timmens]

In lcm.functools, we provide functions allow_only_kwargs and allow_args. These change the parameter kind of the function arguments.

They work as follows:

def f(a, /, *, b):
   return a + b

f(a=1, b=1)  # error because a is positional-only
f(1, 1)  # error because b is keyword-only

allow_only_kwargs(f)(a=1, b=1)  # no error
allow_args(f)(1, 1)  # no error

However, the type annotations of the product of these decorators are not optimal. For example, we currently cannot signal that the function returned by allow_only_kwargs has only keyword-only arguments but is otherwise identical to the input function.

Goal

• General: Add more information through typing
• Explicit: Add information that decorated functions are identical to the input functions except for the changed parameter kind.

Links

• https://stackoverflow.com/questions/76644359/how-to-type-hint-a-function-which-takes-a-callable-and-its-required-positional-a

[hmgaudecker]

Resolution for the moment: Not expressible in Python's type system

This is a fundamental gap in Python's type system, not a limitation of any specific type checker.

Why it can't be done

ParamSpec (PEP 612) captures a full parameter specification but deliberately excluded any mechanism to transform
parameter kinds. There is no way to express "same parameters and return type, but all keyword-only" (or vice versa).

• ParamSpec requires *args: P.args followed immediately by **kwargs: P.kwargs — you cannot insert keyword-only params between them
• Concatenate can only prepend positional-only params to a ParamSpec
• The Protocol-with-__call__ workaround is rejected by pyright (correctly per spec); mypy accepts it but that's considered a mypy bug
• Unpack[TypedDict] (PEP 692) can type **kwargs precisely for a known fixed signature, but cannot be parameterized
  generically over a TypeVar, so it doesn't help for a generic decorator

Upstream tracking

• python/typing#1009 — ParamSpec: No support for adding keyword-only argument (open since Jan 2022, no resolution)
• Eric Traut (pyright maintainer) confirmed in python/typing#1488 there is currently no valid way to annotate this pattern

Current state

The existing Callable[..., ReturnType] signature is the most honest, checker-compatible annotation. Using Callable[P, R] → Callable[P, R] with ParamSpec would be worse — it falsely implies parameter kinds are preserved when they aren't.