I’m not sure if there is already an existing solution or proposal for this (the closest thing I saw was https://peps.python.org/pep-0698/ but it is not quite the thing I need. I also, tried to achieve something with ParamSpec and Concatenate but it didn’t quite work for me either), but i encounter this problem quite a lot.
Whenever I create a class or a function, I like to have full documentation and annotations for each parameter to ease the work of users when using it. The users can have autocompletion from their IDE and a convinient popup with the parameter documentation as they are writing the values.
However, when inheriting from the class (in order to add additional attributes) or wrapping the function (once again, to add an additional parameter).
I would need to either:
copy and paste every single parameter annotation and documentation onto the new function, which causes code duplications and a large risk of outdated documentation whenever changes are done to the original signature.
Define the original parameters as *args, **kwargs and refering the user to a separate documentation in which case, the user loses the convinience of having the relveant information infront of their eyes as they are using the new function. (After all, IDEs have no way of knowing that these dynamic parameters exist solely to be passed down to the original function)
I suggest we have some kind of an
@extends decorator, similar to the
@wraps decorator in functools, which can be used as follows:
class A: def __init__(self, param1: int, param2: str): """ :param param1: Documentation for param1 :param param2: Documentation for param2 """ pass class B(A): @extends(A.__init__) def __init__(self, param3: int, *args, **kwargs): """ :param param3: Documentation for param3 """ super().__init__(*args, **kwargs)
The usage of the decorator will tell IDE’s that the decorated function is expecting to receive the exact same arguments of the original function (documentation, and annotations are the exact same), but with the addition of the new static parameters. IDE’s will be able to show the combined documentation and annotations of all the parameters, and would be able to warn when a incorrect dynamic parameter is passed (when the parameter doesn’t belong to the original function or the wrapped function.)
The decorator is meant to specifically be used when there are absolutly nothing done with the dynamic parameters except for passing them on to the original callable. Any other usage could be result in a warning.
There are some edge cases in regards to positional only arguments, but we can either forbid cases that cause ambiguity or forbid their usage with the decorator alltogether for simplicitly sake.