Consider the following example:
class A:
"""
Simple
:param a: parameter a explained
"""
def __init__(self, a):
self._a = a
class B(A):
def __init__(self, a, b):
"""
More complicated
:param a: parameter a explained. <- repetition here
:param b: parameter b explained.
"""
super().__init__(a) # this call will have to change if `A()` does
self._b = b
class C(A):
def __init__(self, *args, c, **kwargs):
"""
More complicated without repetition of documentation
:param c: parameter c explained.
"""
super().__init__(*args, **kwargs)
self._c = c
What I often find myself doing when sub-classing, is what happens for B: repeating the documentation for A (its superclass).
The reason I do is because if you don't, like for C, IDEs and documentation tools can't resolve the full signature of the constructor and will only provide hints for the new functionality, hiding the documentation of the super class that still applies, even though it works as expected.
To avoid having to repeat like in B, what is the best practice in Python to create a sub-class for some other class, adding a parameter to the constructor, without having to repeat the entire documentation of the superclass in the subclass?
In other words: how can I write class B so that parameter hints in IDEs allow users of the class to see that it takes a and b as a parameter, without specifying all the other parameters besides the new b again?
In this case, it doesn't matter all that much of course, although even here, if the signature of As constructor changes later, the documentation for B will have to be updates as well. But for more complex classes with more parameters, the problem becomes more serious.
Additionally, if the signature of A changes, the call to super().__init__() in Bs constructor will have to change as well, while C keeps working as long as there are no conflicts (i.e. As new parameter on the constructor is not also called c).
