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